@serve.zone/interfaces 32.23.0 → 32.25.0

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