@serve.zone/interfaces 32.24.0 → 32.26.0

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,321 @@
+import type { IPlatformBinding } from './types.js';
+import type {
+  IPlatformObjectStorageEndpoint,
+  TObjectStorageEndpointEnvironment,
+  TObjectStorageEndpointEnvironmentKey,
+} from './objectstorage.js';
+import {
+  createObjectStorageEndpointEnvironment,
+  objectStorageEndpointEnvironmentKeys,
+  validateObjectStorageEndpointEnvironment,
+  validatePlatformObjectStorageBucketName,
+  validatePlatformObjectStorageEndpoint,
+} from './objectstorage.js';
+import type { TServiceRuntimeRefusal, TServiceRuntimeWaitingReason } from '../data/serviceruntime.js';
+import type {
+  IObjectStorageRetentionEvidence,
+  IObjectStorageRetentionEvidenceExpectation,
+  IObjectStorageRetentionIntent,
+  TObjectStorageRetentionEnvironment,
+  TObjectStorageRetentionEnvironmentKey,
+} from './objectstorageretention.js';
+import {
+  createObjectStorageRetentionEnvironment,
+  objectStorageRetentionEnvironmentKeys,
+  validateObjectStorageRetentionEnvironment,
+  validateObjectStorageRetentionEvidence,
+  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);
+
+/** How one binding's environment resolves, in the service runtime vocabulary. */
+type TBindingEnvironmentResolution =
+  | { status: 'composed'; environment: TObjectStorageBindingEnvironment }
+  | { status: 'waiting'; reason: TObjectStorageEnvironmentWaitingReason; message: string }
+  | {
+    status: 'refused';
+    reason: Exclude<TObjectStorageEnvironmentRefusal, 'objectstorage-environment-conflict'>;
+    message: string;
+  };
+
+/**
+ * The one place a binding's environment is decided. `createObjectStorageBindingEnvironment()`
+ * throws its message, `composeObjectStorageServiceEnvironment()` reports its reason.
+ */
+const resolveBindingEnvironment = async (
+  bindingArg: IPlatformBinding,
+  endpointArg: IPlatformObjectStorageEndpoint | null,
+): Promise<TBindingEnvironmentResolution> => {
+  const binding = readDataProperties(bindingArg);
+  if (binding === null || binding.capability !== 'objectstorage') {
+    return { status: 'refused', reason: 'objectstorage-binding-invalid',
+      message: 'objectstorage binding environment requires an objectstorage binding' };
+  }
+  const bindingName = typeof binding.id === 'string' ? binding.id : '(unnamed)';
+  if (validatePlatformObjectStorageBucketName(binding.objectstorageBucketName).length > 0) {
+    return { status: 'refused', reason: 'objectstorage-binding-invalid',
+      message: `objectstorage binding ${bindingName} carries no canonical bucket name; Cloudly owns `
+        + 'it and no environment invents one' };
+  }
+  if (endpointArg === null) {
+    return { status: 'refused', reason: 'objectstorage-endpoint-missing',
+      message: `objectstorage binding ${bindingName} is placed on a node that states no `
+        + 'corestoreObjectStorage endpoint' };
+  }
+  const endpointErrors = validatePlatformObjectStorageEndpoint(endpointArg);
+  if (endpointErrors.length > 0) {
+    return { status: 'refused', reason: 'objectstorage-endpoint-missing', message: endpointErrors[0] };
+  }
+  const bucketName = binding.objectstorageBucketName as string;
+  const endpointEnvironment = createObjectStorageEndpointEnvironment(endpointArg, bucketName);
+  const retention = binding.objectstorageRetention;
+  if (retention === undefined) {
+    return { status: 'composed', environment: endpointEnvironment };
+  }
+  const retentionBinding = readDataProperties(retention);
+  if (retentionBinding === null
+    || validateObjectStorageRetentionIntent(retentionBinding.intent).length > 0) {
+    return { status: 'refused', reason: 'objectstorage-binding-invalid',
+      message: `objectstorage binding ${bindingName} must declare canonical compliance-retention `
+        + 'intent' };
+  }
+  const evidence = retentionBinding.evidence;
+  if (evidence === undefined) {
+    return { status: 'waiting', reason: 'objectstorage-retention-pending',
+      message: `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) {
+    return { status: 'refused', reason: 'objectstorage-binding-invalid',
+      message: 'objectstorage retention evidence must use its exact schema' };
+  }
+  const expectation: IObjectStorageRetentionEvidenceExpectation = {
+    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,
+  };
+  const evidenceErrors = await validateObjectStorageRetentionEvidence(evidence, expectation);
+  if (evidenceErrors.length > 0) {
+    return { status: 'refused', reason: 'objectstorage-binding-invalid', message: evidenceErrors[0] };
+  }
+  const retentionEnvironment = await createObjectStorageRetentionEnvironment(
+    evidence as IObjectStorageRetentionEvidence,
+    expectation,
+  );
+  return { status: 'composed', environment: { ...endpointEnvironment, ...retentionEnvironment } };
+};
+
+/**
+ * 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.
+ *
+ * `composeObjectStorageServiceEnvironment()` answers the same questions with a service runtime
+ * reason instead of an error.
+ */
+export const createObjectStorageBindingEnvironment = async (
+  bindingArg: IPlatformBinding,
+  endpointArg: IPlatformObjectStorageEndpoint,
+): Promise<TObjectStorageBindingEnvironment> => {
+  const resolution = await resolveBindingEnvironment(bindingArg, endpointArg);
+  if (resolution.status !== 'composed') throw new Error(resolution.message);
+  return resolution.environment;
+};
+
+/**
+ * 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;
+};
+
+const findEnvironmentCollisions = (
+  claimedKeysArg: ReadonlySet<string>,
+  keysArg: readonly string[],
+): string[] => keysArg.filter((keyArg) => claimedKeysArg.has(keyArg)).sort();
+
+const describeEnvironmentCollisions = (collisionsArg: readonly string[]): string => (
+  `objectstorage binding environment collides with ${collisionsArg.join(', ')} already set on the `
+    + 'workload'
+);
+
+/**
+ * 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 = findEnvironmentCollisions(
+    new Set(Object.keys(environmentArg)),
+    Object.keys(bindingEnvironmentArg),
+  );
+  if (collisions.length > 0) throw new Error(describeEnvironmentCollisions(collisions));
+  return { ...environmentArg, ...bindingEnvironmentArg };
+};
+
+/** One enabled object-storage binding of a service and the endpoint of the node it is placed on. */
+export interface IObjectStorageBindingEnvironmentSource {
+  binding: IPlatformBinding;
+  /**
+   * The `IClusterNode.data.corestoreObjectStorage` of the node the binding is placed on, `null`
+   * when that node states none. A binding placed on no node is not a source: its service waits as
+   * `bindings-pending`.
+   */
+  endpoint: IPlatformObjectStorageEndpoint | null;
+}
+
+/**
+ * The service runtime waiting reason an object-storage environment reports:
+ * `objectstorage-retention-pending`, a binding that declares compliance retention whose evidence
+ * has not arrived.
+ */
+export type TObjectStorageEnvironmentWaitingReason = Extract<
+  TServiceRuntimeWaitingReason,
+  'objectstorage-retention-pending'
+>;
+
+/**
+ * The service runtime refusals an object-storage environment reports.
+ * `objectstorage-endpoint-missing` is a binding whose node states no valid
+ * `corestoreObjectStorage`; `objectstorage-binding-invalid` a binding
+ * `createObjectStorageBindingEnvironment()` refuses (not `objectstorage`, no canonical bucket, no
+ * canonical retention intent, or evidence that does not prove this binding);
+ * `objectstorage-environment-conflict` a name the service's own environment or another binding
+ * already sets.
+ */
+export type TObjectStorageEnvironmentRefusal = Extract<
+  TServiceRuntimeRefusal,
+  | 'objectstorage-endpoint-missing'
+  | 'objectstorage-binding-invalid'
+  | 'objectstorage-environment-conflict'
+>;
+
+/** A service's environment with every object-storage binding added, or the one reason it is not. */
+export type TObjectStorageServiceEnvironmentComposition =
+  | { status: 'composed'; environment: Record<string, string> }
+  | {
+    status: 'waiting';
+    reason: TObjectStorageEnvironmentWaitingReason;
+    bindingId: string;
+    message: string;
+  }
+  | { status: 'refused'; reason: TObjectStorageEnvironmentRefusal; bindingId: string; message: string };
+
+/**
+ * The service's own environment with the environment of every enabled object-storage binding
+ * added, or the service runtime reason it cannot be — so a producer reports the contract's
+ * verdict instead of classifying its errors.
+ *
+ * Each binding's names are `createObjectStorageBindingEnvironment()`'s from its node's endpoint,
+ * added as `mergeObjectStorageBindingEnvironment()` adds them. Bindings are taken in id order, so
+ * the verdict does not depend on the order of `sourcesArg`. A refusal outranks a wait, because a
+ * wait resolves on its own and a refusal never does: a binding waiting for retention evidence
+ * already claims all twenty of its names, so a collision with it is refused now, not once its
+ * evidence arrives. The first refusal is answered, otherwise the first wait, otherwise the
+ * composed environment. The inputs are not changed.
+ */
+export const composeObjectStorageServiceEnvironment = async (
+  serviceEnvironmentArg: Readonly<Record<string, string>>,
+  sourcesArg: readonly IObjectStorageBindingEnvironmentSource[],
+): Promise<TObjectStorageServiceEnvironmentComposition> => {
+  const sources = [...sourcesArg].sort((leftArg, rightArg) => (
+    leftArg.binding.id < rightArg.binding.id ? -1 : leftArg.binding.id > rightArg.binding.id ? 1 : 0
+  ));
+  let environment: Record<string, string> = { ...serviceEnvironmentArg };
+  const claimedKeys = new Set(Object.keys(environment));
+  let wait: Extract<TObjectStorageServiceEnvironmentComposition, { status: 'waiting' }> | null = null;
+  for (const source of sources) {
+    const bindingId = source.binding.id;
+    const resolution = await resolveBindingEnvironment(source.binding, source.endpoint);
+    if (resolution.status === 'refused') {
+      return { status: 'refused', reason: resolution.reason, bindingId, message: resolution.message };
+    }
+    const keys: readonly string[] = resolution.status === 'composed'
+      ? Object.keys(resolution.environment)
+      : objectStorageBindingEnvironmentKeys;
+    const collisions = findEnvironmentCollisions(claimedKeys, keys);
+    if (collisions.length > 0) {
+      return { status: 'refused', reason: 'objectstorage-environment-conflict', bindingId,
+        message: describeEnvironmentCollisions(collisions) };
+    }
+    for (const key of keys) claimedKeys.add(key);
+    if (resolution.status === 'composed') {
+      environment = { ...environment, ...resolution.environment };
+    } else {
+      wait ??= { status: 'waiting', reason: resolution.reason, bindingId, message: resolution.message };
+    }
+  }
+  return wait ?? { status: 'composed', environment };
+};

package/ts/platform/objectstorageretention.ts

@@ -370,3 +370,144 @@ export const validatePlatformBindingObjectStorageRetention = async (
   }
   return validateObjectStorageRetentionBinding(bindingArg.objectstorageRetention, expectedArg);
 };
+
+/**
+ * The non-secret environment names that tell a workload which retention its bucket carries.
+ *
+ * The names are the ones the cluster relay handed workloads on the Docker path, so an application
+ * that read them keeps working unchanged. Every value is a projection of verified
+ * `IObjectStorageRetentionEvidence`; none is a credential.
+ *
+ * - `S3_RETENTION_MODE`: `intent.mode`, always `compliance`.
+ * - `S3_RETENTION_POLICY_ID`: `intent.policyId`.
+ * - `S3_RETENTION_DURATION_SECONDS`: `intent.retentionDurationSeconds` in decimal.
+ * - `S3_RETENTION_INTENT_SHA256`: `intentSha256`.
+ * - `S3_RETENTION_SENTINEL_KEY`: `receipt.sentinelKey`.
+ * - `S3_RETENTION_CONFIGURED_AT`: `receipt.configuredAt`, Unix milliseconds in decimal.
+ * - `S3_RETENTION_SENTINEL_CREATED_AT`: `receipt.sentinel.createdAt`, Unix milliseconds in decimal.
+ * - `S3_RETENTION_SENTINEL_RETAIN_UNTIL`: `receipt.sentinel.retainUntil`, Unix milliseconds in
+ *   decimal.
+ * - `S3_RETENTION_SENTINEL_PAYLOAD_SHA256`: `receipt.sentinel.payloadSha256`.
+ * - `S3_RETENTION_SENTINEL_METADATA_SHA256`: `receipt.sentinel.metadataSha256`.
+ * - `S3_RETENTION_SENTINEL_ETAG`: `receipt.sentinel.etag`.
+ */
+export const objectStorageRetentionEnvironmentKeys = Object.freeze([
+  'S3_RETENTION_MODE',
+  'S3_RETENTION_POLICY_ID',
+  'S3_RETENTION_DURATION_SECONDS',
+  'S3_RETENTION_INTENT_SHA256',
+  'S3_RETENTION_SENTINEL_KEY',
+  'S3_RETENTION_CONFIGURED_AT',
+  'S3_RETENTION_SENTINEL_CREATED_AT',
+  'S3_RETENTION_SENTINEL_RETAIN_UNTIL',
+  'S3_RETENTION_SENTINEL_PAYLOAD_SHA256',
+  'S3_RETENTION_SENTINEL_METADATA_SHA256',
+  'S3_RETENTION_SENTINEL_ETAG',
+] as const);
+
+export type TObjectStorageRetentionEnvironmentKey =
+  typeof objectStorageRetentionEnvironmentKeys[number];
+
+export type TObjectStorageRetentionEnvironment = {
+  [TKey in TObjectStorageRetentionEnvironmentKey]: string;
+};
+
+/**
+ * The retention environment of evidence that proves `expectedArg`.
+ *
+ * The evidence is validated against the expectation first, with the same validator every other
+ * consumer of retention evidence uses; the first reason it is refused is thrown. A workload is
+ * never told about a retention nobody proved.
+ */
+export const createObjectStorageRetentionEnvironment = async (
+  evidenceArg: IObjectStorageRetentionEvidence,
+  expectedArg: IObjectStorageRetentionEvidenceExpectation,
+): Promise<TObjectStorageRetentionEnvironment> => {
+  const errors = await validateObjectStorageRetentionEvidence(evidenceArg, expectedArg);
+  if (errors.length > 0) throw new Error(errors[0]);
+  return {
+    S3_RETENTION_MODE: evidenceArg.intent.mode,
+    S3_RETENTION_POLICY_ID: evidenceArg.intent.policyId,
+    S3_RETENTION_DURATION_SECONDS: String(evidenceArg.intent.retentionDurationSeconds),
+    S3_RETENTION_INTENT_SHA256: evidenceArg.intentSha256,
+    S3_RETENTION_SENTINEL_KEY: evidenceArg.receipt.sentinelKey,
+    S3_RETENTION_CONFIGURED_AT: String(evidenceArg.receipt.configuredAt),
+    S3_RETENTION_SENTINEL_CREATED_AT: String(evidenceArg.receipt.sentinel.createdAt),
+    S3_RETENTION_SENTINEL_RETAIN_UNTIL: String(evidenceArg.receipt.sentinel.retainUntil),
+    S3_RETENTION_SENTINEL_PAYLOAD_SHA256: evidenceArg.receipt.sentinel.payloadSha256,
+    S3_RETENTION_SENTINEL_METADATA_SHA256: evidenceArg.receipt.sentinel.metadataSha256,
+    S3_RETENTION_SENTINEL_ETAG: evidenceArg.receipt.sentinel.etag,
+  };
+};
+
+const canonicalDecimalPattern = /^[1-9][0-9]*$/;
+
+const readCanonicalPositiveInteger = (valueArg: unknown): number | undefined => (
+  typeof valueArg === 'string'
+  && canonicalDecimalPattern.test(valueArg)
+  && Number.isSafeInteger(Number(valueArg))
+    ? Number(valueArg)
+    : undefined
+);
+
+/**
+ * Validates a retention environment on its own: exactly its eleven keys, canonical values, an
+ * intent digest that matches the stated intent, and sentinel timestamps that agree with the
+ * duration. It cannot prove the authority or the bucket the evidence was bound to — the
+ * environment does not carry them — so it judges the shape a workload reads, not the proof.
+ */
+export const validateObjectStorageRetentionEnvironment = async (
+  environmentArg: unknown,
+  pathArg = 'objectstorage retention environment',
+): Promise<string[]> => {
+  if (!isRecord(environmentArg)
+    || !hasExactKeys(environmentArg, objectStorageRetentionEnvironmentKeys)
+    || objectStorageRetentionEnvironmentKeys.some((keyArg) => (
+      typeof environmentArg[keyArg] !== 'string'
+    ))) {
+    return [`${pathArg} must contain exactly its string keys`];
+  }
+  const environment = environmentArg as TObjectStorageRetentionEnvironment;
+  const errors: string[] = [];
+  const duration = readCanonicalPositiveInteger(environment.S3_RETENTION_DURATION_SECONDS);
+  const intent = {
+    mode: environment.S3_RETENTION_MODE,
+    policyId: environment.S3_RETENTION_POLICY_ID,
+    retentionDurationSeconds: duration,
+  };
+  const intentErrors = validateObjectStorageRetentionIntent(intent, `${pathArg} intent`);
+  errors.push(...intentErrors);
+  if (!sha256Pattern.test(environment.S3_RETENTION_INTENT_SHA256)
+    || intentErrors.length === 0
+      && environment.S3_RETENTION_INTENT_SHA256 !== await computeObjectStorageRetentionIntentSha256(
+        intent as IObjectStorageRetentionIntent,
+      )) {
+    errors.push(`${pathArg} S3_RETENTION_INTENT_SHA256 must be the digest of the stated intent`);
+  }
+  if (!sentinelKeyPattern.test(environment.S3_RETENTION_SENTINEL_KEY)) {
+    errors.push(`${pathArg} S3_RETENTION_SENTINEL_KEY must be canonical`);
+  }
+  const configuredAt = readCanonicalPositiveInteger(environment.S3_RETENTION_CONFIGURED_AT);
+  const createdAt = readCanonicalPositiveInteger(environment.S3_RETENTION_SENTINEL_CREATED_AT);
+  const retainUntil = readCanonicalPositiveInteger(environment.S3_RETENTION_SENTINEL_RETAIN_UNTIL);
+  if (configuredAt === undefined
+    || createdAt === undefined
+    || retainUntil === undefined
+    || createdAt < configuredAt) {
+    errors.push(`${pathArg} timestamps must be canonical positive decimals in order`);
+  } else if (intentErrors.length === 0) {
+    try {
+      if (retainUntil !== createObjectStorageRetentionRetainUntil(createdAt, duration as number)) {
+        errors.push(`${pathArg} S3_RETENTION_SENTINEL_RETAIN_UNTIL must equal createdAt plus duration`);
+      }
+    } catch {
+      errors.push(`${pathArg} S3_RETENTION_SENTINEL_RETAIN_UNTIL arithmetic must be safe`);
+    }
+  }
+  if (!sha256Pattern.test(environment.S3_RETENTION_SENTINEL_PAYLOAD_SHA256)
+    || !sha256Pattern.test(environment.S3_RETENTION_SENTINEL_METADATA_SHA256)
+    || !etagPattern.test(environment.S3_RETENTION_SENTINEL_ETAG)) {
+    errors.push(`${pathArg} sentinel digests and ETag must be canonical`);
+  }
+  return errors;
+};