@serve.zone/interfaces 32.23.0 → 32.25.0

package/ts/data/runtimelocalstorageclaim.ts

@@ -6,17 +6,77 @@ import { snapshotRuntimeSessionBinding } from './runtimesession.js';
 import { captureNetwork, networkController, networkDigest, networkEqual, networkHash, networkId,
   networkNodeId, networkRecord, networkReference, networkReferenceOf, networkRevision, requireNetwork,
 } from '../private/networkcontract.js';
+import { parseCanonicalIpAddress } from '../private/ipaddress.js';
 import { isRuntimeIdentityNumber } from '../private/runtimepolicy.js';
 import { createStorageContractReaders } from '../private/storagecontract.js';
 
+/** A node-local directory the node derives from the claim's identity under a root only the node knows. */
+export type TRuntimeLocalStorageDirectorySource = {
+  kind: 'directory';
+};
+
+/**
+ * A directory on an NFS export. The node mounts `server:export` and uses `subPath` below it.
+ *
+ * `server` is a lowercase fully qualified hostname or a canonical IP literal, on the standard port.
+ * `export` is the canonical absolute path the server exports, `/` included. `subPath` is the
+ * volume's directory below the export, as canonical relative segments, or `.` for the export
+ * itself. `version` pins one protocol version. NFS authenticates the node's host, not a user, so
+ * the source names no credential.
+ */
+export type TRuntimeLocalStorageNfsSource = {
+  kind: 'nfs';
+  server: string;
+  export: string;
+  subPath: string;
+  version: TRuntimeLocalStorageNfsVersion;
+};
+
 /**
- * Where a local storage claim's bytes live, named by kind and never by path.
+ * A directory on an SMB share. The node mounts `//server/share` and uses `subPath` below it.
  *
- * `directory` is a node-local directory the node derives from the claim's identity under a root
- * only the node knows. Network filesystems join this union as further kinds; their credentials
- * travel as secrets and never inside a claim.
+ * `server` and `subPath` follow the NFS rules; `share` is one share name. `version` pins one
+ * dialect. `credential` names the credential authority the node authenticates with, by reference
+ * only: the claim never carries a user name, password or domain, and the node resolves the material
+ * through the controller's secret delivery.
  */
-export type TRuntimeLocalStorageSource = { kind: 'directory' };
+export type TRuntimeLocalStorageSmbSource = {
+  kind: 'smb';
+  server: string;
+  share: string;
+  subPath: string;
+  version: TRuntimeLocalStorageSmbVersion;
+  credential: IRuntimeAuthorityReference;
+};
+
+/**
+ * Where a local storage claim's bytes live, named by kind and never by a node's host path.
+ *
+ * A network source names the remote location and nothing about how to mount it: no mount option,
+ * no port and no credential value. The node derives every mount parameter from these fields alone.
+ * The kinds are type aliases, as `{ kind: 'directory' }` always was, so a source stays assignable
+ * to a plain record.
+ */
+export type TRuntimeLocalStorageSource =
+  | TRuntimeLocalStorageDirectorySource
+  | TRuntimeLocalStorageNfsSource
+  | TRuntimeLocalStorageSmbSource;
+
+/**
+ * The NFS protocol versions a claim may pin, spelled as the kernel's NFS `vers=` parameter spells
+ * them. NFS version 4 is always stated with its minor version: the bare `4` negotiates one, which
+ * the kernel keeps only for backward compatibility, and a claim must mean the same mount on every
+ * node. Version 2 is refused.
+ */
+export type TRuntimeLocalStorageNfsVersion = (typeof runtimeLocalStorageClaimContract.nfsVersions)[number];
+
+/**
+ * The SMB dialects a claim may pin, spelled as the kernel's CIFS `vers=` parameter spells them.
+ * Only SMB 3 dialects, the first that encrypt; the kernel refuses 1.0 and 2.0 unless built with
+ * insecure legacy dialects. `3` alone negotiates one and is refused for the same reason as a bare
+ * NFS `4`.
+ */
+export type TRuntimeLocalStorageSmbVersion = (typeof runtimeLocalStorageClaimContract.smbVersions)[number];
 
 /** The owner and permission bits a node gives an `empty` volume's root directory when it creates it. */
 export interface IRuntimeLocalStorageOwnership {
@@ -39,15 +99,19 @@ export interface IRuntimeLocalStorageMount {
 export type TRuntimeLocalStorageLifecycle = 'bound' | 'purge';
 
 /**
- * A controller's authority for one retained, node-local volume of one service.
+ * A controller's authority for one retained volume of one service, mounted on one node.
  *
- * Cloudly and Onebox issue it alike. It names the volume by identity only: no host path, no
- * device, no mount option and no credential. The node resolves the identity to its own storage.
+ * Cloudly and Onebox issue it alike. It never names a host path, a device, a mount option or a
+ * credential value. A `directory` source names the volume by identity only, and the node resolves
+ * it to its own storage; a network source names the remote directory and, for SMB, the credential
+ * by reference.
  *
  * `initialization` says what the node does when the volume does not exist yet. `empty` creates an
  * empty root with `initialOwnership`, which it must state, so a workload that runs as the image's
  * own user never meets a root-owned directory by accident. `import` waits for the volume's bytes to
- * be imported and states no ownership: an imported tree keeps the ownership it carries.
+ * be imported and states no ownership: an imported tree keeps the ownership it carries. SMB carries
+ * no POSIX ownership, so the node presents an SMB volume with `initialOwnership`, and an `smb`
+ * source is always `empty`.
  */
 export interface IRuntimeLocalStorageClaim {
   id: string;
@@ -104,6 +168,16 @@ export const runtimeLocalStorageClaimContract = Object.freeze({
   reclaimPolicy: 'retain',
   /** Every permission bit a claim may state: setgid, sticky and the rwx triplets. */
   directoryModeBits: 0o3777,
+  nfsVersions: ['3', '4.0', '4.1', '4.2'],
+  smbVersions: ['3.0', '3.02', '3.1.1'],
+  /** The longest hostname a network source may name, in characters. */
+  maximumServerLength: 253,
+  /** The longest `export` or `subPath`, in characters; every character is printable ASCII. */
+  maximumPathLength: 1024,
+  /** The longest segment of an `export` or `subPath`. */
+  maximumSegmentLength: 255,
+  /** The longest SMB share name. */
+  maximumShareLength: 80,
 } as const);
 
 const fail = (): never => { throw new Error(runtimeLocalStorageClaimContract.error); };
@@ -112,7 +186,90 @@ const { readMountPath } = createStorageContractReaders(fail);
 const claimStates = ['ready', 'import-required', 'purged', 'uncertain'] as const;
 const responseStatuses = ['accepted', 'replay', 'historical'] as const;
 
+const hostnameLabelPattern = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * Printable ASCII without a space. One spelling per name, so two claims cannot name one directory
+ * two ways, and nothing a mount source or an option string reads as a separator.
+ */
+const printableAsciiPattern = /^[\x21-\x7e]+$/;
+/** A comma or `=` would read as a mount option; the rest have meaning in a mount source or an SMB name. */
+const pathSegmentForbiddenPattern = /["*,/:<=>?\\|]/;
+/** SMB refuses these in a share name, beyond what it refuses in a path segment. */
+const shareForbiddenPattern = /[+;\[\]]/;
+
+/**
+ * A lowercase fully qualified hostname of two or more labels whose last label is not numeric, or a
+ * canonical IP literal. One label would resolve through each node's own search domains; a numeric
+ * last label would let a non-canonical address pass as a hostname. There is no port and no
+ * userinfo: the node connects to the protocol's standard port.
+ */
+const serverOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string');
+  if (parseCanonicalIpAddress(valueArg) !== null) return valueArg;
+  const labels = valueArg.split('.');
+  requireNetwork(valueArg.length <= runtimeLocalStorageClaimContract.maximumServerLength && labels.length >= 2
+    && labels.every((labelArg) => hostnameLabelPattern.test(labelArg))
+    && !/^[0-9]+$/.test(labels[labels.length - 1]));
+  return valueArg;
+};
+
+const isPathSegment = (valueArg: string): boolean =>
+  valueArg.length <= runtimeLocalStorageClaimContract.maximumSegmentLength
+  && printableAsciiPattern.test(valueArg) && !pathSegmentForbiddenPattern.test(valueArg)
+  && valueArg !== '.' && valueArg !== '..';
+
+const isRelativeSegments = (valueArg: string): boolean =>
+  valueArg.length <= runtimeLocalStorageClaimContract.maximumPathLength
+  && valueArg.split('/').every(isPathSegment);
+
+/** `/`, or `/` followed by canonical segments without a trailing slash. */
+const exportOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && valueArg.length <= runtimeLocalStorageClaimContract.maximumPathLength
+    && valueArg.startsWith('/') && (valueArg === '/' || isRelativeSegments(valueArg.slice(1))));
+  return valueArg;
+};
+
+/** `.`, or canonical relative segments. */
+const subPathOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && (valueArg === '.' || isRelativeSegments(valueArg)));
+  return valueArg;
+};
+
+const shareOf = (valueArg: unknown): string => {
+  requireNetwork(typeof valueArg === 'string' && valueArg.length <= runtimeLocalStorageClaimContract.maximumShareLength
+    && isPathSegment(valueArg) && !shareForbiddenPattern.test(valueArg));
+  return valueArg;
+};
+
+const literalOf = <TLiteral extends string>(valueArg: unknown, allowedArg: readonly TLiteral[]): TLiteral => {
+  requireNetwork((allowedArg as readonly unknown[]).includes(valueArg));
+  return valueArg as TLiteral;
+};
+
 const sourceOf = (valueArg: unknown): TRuntimeLocalStorageSource => {
+  requireNetwork(valueArg !== null && typeof valueArg === 'object');
+  const { kind } = valueArg as Record<string, unknown>;
+  if (kind === 'nfs') {
+    const value = networkRecord(valueArg, ['kind', 'server', 'export', 'subPath', 'version']);
+    return {
+      kind: 'nfs',
+      server: serverOf(value.server),
+      export: exportOf(value.export),
+      subPath: subPathOf(value.subPath),
+      version: literalOf(value.version, runtimeLocalStorageClaimContract.nfsVersions),
+    };
+  }
+  if (kind === 'smb') {
+    const value = networkRecord(valueArg, ['kind', 'server', 'share', 'subPath', 'version', 'credential']);
+    return {
+      kind: 'smb',
+      server: serverOf(value.server),
+      share: shareOf(value.share),
+      subPath: subPathOf(value.subPath),
+      version: literalOf(value.version, runtimeLocalStorageClaimContract.smbVersions),
+      credential: networkReference(value.credential),
+    };
+  }
   const value = networkRecord(valueArg, ['kind']);
   requireNetwork(value.kind === 'directory');
   return { kind: 'directory' };
@@ -142,6 +299,8 @@ export const snapshotRuntimeLocalStorageClaim = (valueArg: unknown): IRuntimeLoc
     || (value.initialization === 'import' && value.initialOwnership === null));
   requireNetwork(value.accessMode === 'ReadWriteOnce' && value.reclaimPolicy === 'retain');
   requireNetwork(value.lifecycle === 'bound' || (value.lifecycle === 'purge' && previous !== null));
+  const source = sourceOf(value.source);
+  requireNetwork(source.kind !== 'smb' || value.initialization === 'empty');
   return {
     id, generation, previous,
     controller: networkController(value.controller),
@@ -151,7 +310,7 @@ export const snapshotRuntimeLocalStorageClaim = (valueArg: unknown): IRuntimeLoc
     runtimeNamespace: networkId(value.runtimeNamespace),
     serviceId: networkId(value.serviceId),
     volumeId: networkId(value.volumeId),
-    source: sourceOf(value.source),
+    source,
     initialization: value.initialization as IRuntimeLocalStorageClaim['initialization'],
     initialOwnership: value.initialOwnership === null ? null : ownershipOf(value.initialOwnership),
     mount: mountOf(value.mount),

package/ts/platform/index.ts

@@ -5,6 +5,7 @@ import * as email from './email.js';
 import * as letter from './letter.js';
 import * as logging from './logging.js';
 import * as objectstorage from './objectstorage.js';
+import * as objectstorageenvironment from './objectstorageenvironment.js';
 import * as objectstorageretention from './objectstorageretention.js';
 import * as pushnotification from './pushnotification.js';
 import * as sip from './sip.js';
@@ -21,6 +22,7 @@ export {
   letter,
   logging,
   objectstorage,
+  objectstorageenvironment,
   objectstorageretention,
   pushnotification,
   sip,
@@ -32,6 +34,7 @@ export {
 
 export * from './storage.js';
 export * from './objectstorage.js';
+export * from './objectstorageenvironment.js';
 export * from './objectstorageretention.js';
 export * from './storagemigration.js';
 export * from './types.js';

package/ts/platform/objectstorage.ts

@@ -31,3 +31,183 @@ export const validatePlatformObjectStorageBucketName = (
   }
   return [];
 };
+
+/**
+ * Where a workload reaches one node's S3 object storage, and the region it signs requests for.
+ *
+ * Non-secret and value-free: it says where, never with what. The access key and secret stay in
+ * the binding's sealed Secret set. Corestore is node-local, so this is a fact about the node that
+ * holds the bucket, stated by an administrator on `IClusterNode.data.corestoreObjectStorage`;
+ * Cloudly reads it from there and never derives a port, a scheme or a region.
+ */
+export interface IPlatformObjectStorageEndpoint {
+  /**
+   * The canonical `http:` or `https:` origin of the S3 API, for example `http://192.0.2.15:9000`:
+   * a host, an optional port, and nothing else — no path, query, fragment, userinfo, trailing
+   * slash or default port. The host is the one a workload on that node can reach.
+   */
+  endpoint: string;
+  /** The SigV4 signing region the object storage answers for, for example `us-east-1`. */
+  region: string;
+}
+
+export const platformObjectStorageEndpointLimits = Object.freeze({
+  maximumEndpointLength: 2048,
+  maximumRegionLength: 64,
+});
+
+const platformObjectStorageRegionPattern = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  Boolean(valueArg)
+  && typeof valueArg === 'object'
+  && !Array.isArray(valueArg)
+  && (Object.getPrototypeOf(valueArg) === Object.prototype
+    || Object.getPrototypeOf(valueArg) === null)
+);
+
+/** Validates an object-storage endpoint and names every reason it is refused. */
+export const validatePlatformObjectStorageEndpoint = (
+  valueArg: unknown,
+  pathArg = 'objectstorage endpoint',
+): string[] => {
+  if (!isPlainObject(valueArg)
+    || Object.keys(valueArg).length !== 2
+    || !Object.hasOwn(valueArg, 'endpoint')
+    || !Object.hasOwn(valueArg, 'region')) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  const endpoint = valueArg.endpoint;
+  if (typeof endpoint !== 'string'
+    || endpoint.length === 0
+    || endpoint.length > platformObjectStorageEndpointLimits.maximumEndpointLength) {
+    errors.push(`${pathArg} endpoint must be a string of 1 to `
+      + `${platformObjectStorageEndpointLimits.maximumEndpointLength} characters`);
+  } else {
+    let parsedEndpoint: URL | undefined;
+    try {
+      parsedEndpoint = new URL(endpoint);
+    } catch {
+      errors.push(`${pathArg} endpoint must be a parsable URL`);
+    }
+    if (parsedEndpoint) {
+      if (parsedEndpoint.protocol !== 'http:' && parsedEndpoint.protocol !== 'https:') {
+        errors.push(`${pathArg} endpoint must use the http or https scheme`);
+      }
+      if (parsedEndpoint.username || parsedEndpoint.password) {
+        errors.push(`${pathArg} endpoint must not carry userinfo`);
+      }
+      if (parsedEndpoint.origin !== endpoint) {
+        errors.push(`${pathArg} endpoint must be a canonical origin without a path, query, `
+          + 'fragment, trailing slash or default port');
+      }
+    }
+  }
+  if (typeof valueArg.region !== 'string'
+    || !platformObjectStorageRegionPattern.test(valueArg.region)) {
+    errors.push(`${pathArg} region must be 1 to `
+      + `${platformObjectStorageEndpointLimits.maximumRegionLength} lowercase letters, digits `
+      + 'and inner hyphens');
+  }
+  return errors;
+};
+
+/**
+ * The non-secret environment names that tell a workload where its bucket is.
+ *
+ * These are the names Corestore has always handed a workload for a bucket, so an application that
+ * read them keeps working unchanged. The six credential aliases (`S3_ACCESS_KEY`,
+ * `S3_ACCESS_KEY_ID`, `S3_SECRET_KEY`, `S3_SECRET_ACCESS_KEY`, `AWS_ACCESS_KEY_ID`,
+ * `AWS_SECRET_ACCESS_KEY`) are not among them: they are Secrets and reach the workload only through
+ * the binding's sealed Secret set.
+ *
+ * - `S3_ENDPOINT`, `AWS_ENDPOINT_URL`: the endpoint origin, identical.
+ * - `S3_ENDPOINT_HOST`: the origin's host, as the URL states it (an IPv6 literal keeps its brackets).
+ * - `S3_PORT`: the origin's port in decimal, `80` or `443` when the origin states none.
+ * - `S3_USE_SSL`: `true` for an `https:` origin, `false` for `http:`.
+ * - `S3_REGION`, `AWS_REGION`: the signing region, identical.
+ * - `S3_BUCKET`: the binding's bucket, `IPlatformBinding.objectstorageBucketName`.
+ * - `AWS_S3_FORCE_PATH_STYLE`: always `true` — a node-local origin has no wildcard DNS and a bucket
+ *   name may contain dots, so path-style addressing is the only one that reaches the bucket.
+ */
+export const objectStorageEndpointEnvironmentKeys = Object.freeze([
+  'S3_ENDPOINT',
+  'S3_ENDPOINT_HOST',
+  'S3_PORT',
+  'S3_REGION',
+  'S3_BUCKET',
+  'S3_USE_SSL',
+  'AWS_ENDPOINT_URL',
+  'AWS_REGION',
+  'AWS_S3_FORCE_PATH_STYLE',
+] as const);
+
+export type TObjectStorageEndpointEnvironmentKey =
+  typeof objectStorageEndpointEnvironmentKeys[number];
+
+export type TObjectStorageEndpointEnvironment = {
+  [TKey in TObjectStorageEndpointEnvironmentKey]: string;
+};
+
+/**
+ * The endpoint environment for one bucket.
+ *
+ * Throws the first reason the endpoint or the bucket name is refused; nothing is defaulted.
+ */
+export const createObjectStorageEndpointEnvironment = (
+  endpointArg: IPlatformObjectStorageEndpoint,
+  bucketNameArg: string,
+): TObjectStorageEndpointEnvironment => {
+  const errors = [
+    ...validatePlatformObjectStorageEndpoint(endpointArg),
+    ...validatePlatformObjectStorageBucketName(bucketNameArg),
+  ];
+  if (errors.length > 0) throw new Error(errors[0]);
+  const origin = new URL(endpointArg.endpoint);
+  const useSsl = origin.protocol === 'https:';
+  return {
+    S3_ENDPOINT: endpointArg.endpoint,
+    S3_ENDPOINT_HOST: origin.hostname,
+    S3_PORT: origin.port || (useSsl ? '443' : '80'),
+    S3_REGION: endpointArg.region,
+    S3_BUCKET: bucketNameArg,
+    S3_USE_SSL: useSsl ? 'true' : 'false',
+    AWS_ENDPOINT_URL: endpointArg.endpoint,
+    AWS_REGION: endpointArg.region,
+    AWS_S3_FORCE_PATH_STYLE: 'true',
+  };
+};
+
+/**
+ * Validates an endpoint environment: exactly its nine keys, each value the one
+ * `createObjectStorageEndpointEnvironment()` derives from the same endpoint and bucket.
+ */
+export const validateObjectStorageEndpointEnvironment = (
+  environmentArg: unknown,
+  pathArg = 'objectstorage endpoint environment',
+): string[] => {
+  if (!isPlainObject(environmentArg)
+    || Object.keys(environmentArg).length !== objectStorageEndpointEnvironmentKeys.length
+    || objectStorageEndpointEnvironmentKeys.some((keyArg) => (
+      !Object.hasOwn(environmentArg, keyArg) || typeof environmentArg[keyArg] !== 'string'
+    ))) {
+    return [`${pathArg} must contain exactly its string keys`];
+  }
+  const endpoint = { endpoint: environmentArg.S3_ENDPOINT, region: environmentArg.S3_REGION };
+  const errors = [
+    ...validatePlatformObjectStorageEndpoint(endpoint, pathArg),
+    ...validatePlatformObjectStorageBucketName(environmentArg.S3_BUCKET, `${pathArg} S3_BUCKET`),
+  ];
+  if (errors.length > 0) return errors;
+  const expected = createObjectStorageEndpointEnvironment(
+    endpoint as IPlatformObjectStorageEndpoint,
+    environmentArg.S3_BUCKET as string,
+  );
+  for (const key of objectStorageEndpointEnvironmentKeys) {
+    if (environmentArg[key] !== expected[key]) {
+      errors.push(`${pathArg} ${key} must equal the value derived from its endpoint`);
+    }
+  }
+  return errors;
+};

package/ts/platform/objectstorageenvironment.ts

@@ -0,0 +1,176 @@
+import type { IPlatformBinding } from './types.js';
+import type {
+  IPlatformObjectStorageEndpoint,
+  TObjectStorageEndpointEnvironment,
+  TObjectStorageEndpointEnvironmentKey,
+} from './objectstorage.js';
+import {
+  createObjectStorageEndpointEnvironment,
+  objectStorageEndpointEnvironmentKeys,
+  validateObjectStorageEndpointEnvironment,
+  validatePlatformObjectStorageBucketName,
+} from './objectstorage.js';
+import type {
+  IObjectStorageRetentionEvidence,
+  IObjectStorageRetentionIntent,
+  TObjectStorageRetentionEnvironment,
+  TObjectStorageRetentionEnvironmentKey,
+} from './objectstorageretention.js';
+import {
+  createObjectStorageRetentionEnvironment,
+  objectStorageRetentionEnvironmentKeys,
+  validateObjectStorageRetentionEnvironment,
+  validateObjectStorageRetentionIntent,
+} from './objectstorageretention.js';
+import { isPlainRecord, readDataProperties } from '../private/dataproperties.js';
+
+/**
+ * Every non-secret environment name an object-storage binding can give a workload: the nine
+ * endpoint names first, then the eleven retention names.
+ */
+export const objectStorageBindingEnvironmentKeys = Object.freeze([
+  ...objectStorageEndpointEnvironmentKeys,
+  ...objectStorageRetentionEnvironmentKeys,
+] as const);
+
+export type TObjectStorageBindingEnvironmentKey =
+  | TObjectStorageEndpointEnvironmentKey
+  | TObjectStorageRetentionEnvironmentKey;
+
+/**
+ * The non-secret environment of one object-storage binding: always the endpoint names, and the
+ * retention names exactly when the binding declares compliance retention. Never a credential.
+ */
+export type TObjectStorageBindingEnvironment =
+  | TObjectStorageEndpointEnvironment
+  | (TObjectStorageEndpointEnvironment & TObjectStorageRetentionEnvironment);
+
+/**
+ * The environment Cloudly composes into a workload's runtime configuration for one binding.
+ *
+ * `bindingArg` is the Cloudly binding document and `endpointArg` the
+ * `IClusterNode.data.corestoreObjectStorage` of the node the binding is placed on. Refused by
+ * name, never guessed:
+ *
+ * - a binding that is not `objectstorage` or carries no canonical `objectstorageBucketName`;
+ * - an endpoint that `validatePlatformObjectStorageEndpoint()` refuses;
+ * - a binding that declares `objectstorageRetention` without `evidence`. Its bucket's retention is
+ *   not proven yet, so the workload is not given an environment that would let it run as if its
+ *   bucket were ordinary storage; the caller waits for the evidence.
+ * - evidence that does not prove the binding's own service, binding id, bucket and intent.
+ *
+ * A binding without `objectstorageRetention` gets the endpoint names alone: it promised no
+ * retention, so there is nothing to state.
+ *
+ * The evidence's reconciliation generation and binding-request digest are read from its own
+ * authority: they are what Cloudly checked when it admitted the evidence, and the binding document
+ * does not repeat them. Everything the binding does state is checked again here.
+ */
+export const createObjectStorageBindingEnvironment = async (
+  bindingArg: IPlatformBinding,
+  endpointArg: IPlatformObjectStorageEndpoint,
+): Promise<TObjectStorageBindingEnvironment> => {
+  const binding = readDataProperties(bindingArg);
+  if (binding === null || binding.capability !== 'objectstorage') {
+    throw new Error('objectstorage binding environment requires an objectstorage binding');
+  }
+  const bindingName = typeof binding.id === 'string' ? binding.id : '(unnamed)';
+  if (validatePlatformObjectStorageBucketName(binding.objectstorageBucketName).length > 0) {
+    throw new Error(
+      `objectstorage binding ${bindingName} carries no canonical bucket name; Cloudly owns it and `
+        + 'no environment invents one',
+    );
+  }
+  const bucketName = binding.objectstorageBucketName as string;
+  const endpointEnvironment = createObjectStorageEndpointEnvironment(endpointArg, bucketName);
+  const retention = binding.objectstorageRetention;
+  if (retention === undefined) {
+    return endpointEnvironment;
+  }
+  const retentionBinding = readDataProperties(retention);
+  if (retentionBinding === null
+    || validateObjectStorageRetentionIntent(retentionBinding.intent).length > 0) {
+    throw new Error(
+      `objectstorage binding ${bindingName} must declare canonical compliance-retention intent`,
+    );
+  }
+  const evidence = retentionBinding.evidence;
+  if (evidence === undefined) {
+    throw new Error(
+      `objectstorage binding ${bindingName} declares compliance retention without verified `
+        + 'evidence; its workload environment waits for the evidence',
+    );
+  }
+  const authority = isPlainRecord(evidence) ? readDataProperties(evidence.authority) : null;
+  if (authority === null) {
+    throw new Error('objectstorage retention evidence must use its exact schema');
+  }
+  const retentionEnvironment = await createObjectStorageRetentionEnvironment(
+    evidence as IObjectStorageRetentionEvidence,
+    {
+      serviceId: binding.serviceId as string,
+      bindingId: binding.id as string,
+      reconciliationGeneration: authority.reconciliationGeneration as number,
+      bindingRequestDigest: authority.bindingRequestDigest as string,
+      bucketName,
+      intent: retentionBinding.intent as IObjectStorageRetentionIntent,
+    },
+  );
+  return { ...endpointEnvironment, ...retentionEnvironment };
+};
+
+/**
+ * Validates one binding's environment: the nine endpoint names, the eleven retention names all or
+ * none, and nothing else — so a credential alias, or any other name, is refused.
+ */
+export const validateObjectStorageBindingEnvironment = async (
+  environmentArg: unknown,
+  pathArg = 'objectstorage binding environment',
+): Promise<string[]> => {
+  const environment = readDataProperties(environmentArg);
+  if (environment === null) {
+    return [`${pathArg} must be a plain record of data properties`];
+  }
+  const allowedKeys: readonly string[] = objectStorageBindingEnvironmentKeys;
+  const foreignKeys = Object.keys(environment).filter((keyArg) => !allowedKeys.includes(keyArg));
+  if (foreignKeys.length > 0) {
+    return [`${pathArg} must not contain ${foreignKeys.sort().join(', ')}`];
+  }
+  const endpointEnvironment: Record<string, unknown> = {};
+  for (const key of objectStorageEndpointEnvironmentKeys) {
+    if (Object.hasOwn(environment, key)) endpointEnvironment[key] = environment[key];
+  }
+  const errors = validateObjectStorageEndpointEnvironment(endpointEnvironment, pathArg);
+  const retentionKeys = objectStorageRetentionEnvironmentKeys.filter((keyArg) => (
+    Object.hasOwn(environment, keyArg)
+  ));
+  if (retentionKeys.length > 0) {
+    const retentionEnvironment: Record<string, unknown> = {};
+    for (const key of retentionKeys) retentionEnvironment[key] = environment[key];
+    errors.push(...await validateObjectStorageRetentionEnvironment(retentionEnvironment, pathArg));
+  }
+  return errors;
+};
+
+/**
+ * A workload environment with one binding's environment added.
+ *
+ * Refuses, naming every key, when the environment already holds one of the binding's names: a
+ * service that sets `S3_ENDPOINT` itself, or a second object-storage binding on the same service,
+ * would otherwise have one value silently replace the other. The inputs are not changed.
+ */
+export const mergeObjectStorageBindingEnvironment = (
+  environmentArg: Readonly<Record<string, string>>,
+  bindingEnvironmentArg: TObjectStorageBindingEnvironment,
+): Record<string, string> => {
+  const collisions = Object.keys(bindingEnvironmentArg)
+    .filter((keyArg) => Object.hasOwn(environmentArg, keyArg))
+    .sort();
+  if (collisions.length > 0) {
+    throw new Error(
+      `objectstorage binding environment collides with ${collisions.join(', ')} already set on the `
+        + 'workload',
+    );
+  }
+  return { ...environmentArg, ...bindingEnvironmentArg };
+};