@serve.zone/interfaces 32.24.0 → 32.25.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,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 };
+};

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;
+};

package/ts/requests/node.ts

@@ -4,6 +4,7 @@ import type { ICluster } from '../data/cluster.js';
 import type { IClusterNode, INodeAction, INodeMetricsSample, TNodeActionName } from '../data/clusternode.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
+import type { IPlatformObjectStorageEndpoint } from '../platform/objectstorage.js';
 import type {
   INodeCredentialMetadata,
   INodeCredentialMutationPreconditions,
@@ -282,6 +283,38 @@ export interface IReq_Any_Cloudly_SetClusterNodeCorestoreEndpoint extends plugin
   };
 }
 
+/**
+ * An administrator states where a workload on one node reaches the node's Corestore object
+ * storage, and the region it signs for: `IClusterNode.data.corestoreObjectStorage`.
+ *
+ * A request of its own, separate from `setClusterNodeCorestoreEndpoint`, because the two are
+ * separate facts with separate readers — the relay dials the control endpoint, a workload dials
+ * this one — and setting one never touches the other. A caller that states only the control
+ * endpoint leaves this one as it stands.
+ *
+ * Cloudly validates it with `validatePlatformObjectStorageEndpoint` before it writes and takes the
+ * node's own real-write fence inside the writing transaction, as for the control endpoint.
+ * `objectStorage: null` clears it, which is the same fact as never having set one: no
+ * object-storage environment can be composed for a binding on this node. The endpoint says where,
+ * never with what — no credential travels in this request or in the node document.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeCorestoreObjectStorageEndpoint extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_SetClusterNodeCorestoreObjectStorageEndpoint
+> {
+  method: 'setClusterNodeCorestoreObjectStorageEndpoint';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    /** The node's object-storage endpoint and region, or `null` to state that it has none. */
+    objectStorage: IPlatformObjectStorageEndpoint | null;
+  };
+  response: {
+    /** The node as it now stands, so a caller needs no second read to see what it set. */
+    node: IClusterNode;
+  };
+}
+
 export interface IReq_Any_Cloudly_CreateNodeAction extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Any_Cloudly_CreateNodeAction