@serve.zone/interfaces 32.25.0 → 32.27.0

package/ts/platform/database.ts

@@ -6,3 +6,82 @@ export interface IPlatformDatabaseBindingConfig {
   version?: string;
   extensions?: string[];
 }
+
+/**
+ * Where a workload on one node reaches the node's Corestore database.
+ *
+ * Non-secret and value-free: it says where, never with what. Corestore is node-local, so this is
+ * a fact about the node that holds the database, stated by an administrator on
+ * `IClusterNode.data.corestoreDatabase`. Cloudly reads it from there and hands it to Corestore in
+ * the database binding request, and Corestore addresses the binding's connection values to it —
+ * never to its own public host, which on a converted root is an identity and not an address a
+ * workload can resolve.
+ */
+export interface IPlatformDatabaseEndpoint {
+  /**
+   * The host a workload on that node dials: an IPv4 literal such as `192.0.2.15`, an IPv6 literal
+   * without brackets, or a lowercase DNS name, each exactly as a URL states it.
+   */
+  host: string;
+  /** The TCP port of the database wire protocol, 1 to 65535. */
+  port: number;
+}
+
+export const platformDatabaseEndpointLimits = Object.freeze({
+  maximumHostLength: 253,
+});
+
+const platformDatabaseHostNamePattern =
+  /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+
+const isPlainDatabaseEndpointRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  Boolean(valueArg)
+  && typeof valueArg === 'object'
+  && !Array.isArray(valueArg)
+  && (Object.getPrototypeOf(valueArg) === Object.prototype
+    || Object.getPrototypeOf(valueArg) === null)
+);
+
+/** The host as a URL authority states it: an IPv6 literal in brackets, every other host as is. */
+export const formatPlatformDatabaseEndpointHost = (hostArg: string): string => (
+  hostArg.includes(':') ? `[${hostArg}]` : hostArg
+);
+
+/** Validates a database endpoint and names every reason it is refused. */
+export const validatePlatformDatabaseEndpoint = (
+  valueArg: unknown,
+  pathArg = 'database endpoint',
+): string[] => {
+  if (!isPlainDatabaseEndpointRecord(valueArg)
+    || Object.keys(valueArg).length !== 2
+    || !Object.hasOwn(valueArg, 'host')
+    || !Object.hasOwn(valueArg, 'port')) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  const host = valueArg.host;
+  if (typeof host !== 'string'
+    || host.length === 0
+    || host.length > platformDatabaseEndpointLimits.maximumHostLength) {
+    errors.push(`${pathArg} host must be a string of 1 to `
+      + `${platformDatabaseEndpointLimits.maximumHostLength} characters`);
+  } else {
+    const authorityHost = formatPlatformDatabaseEndpointHost(host);
+    let parsedHost: string | undefined;
+    try {
+      parsedHost = new URL(`http://${authorityHost}/`).hostname;
+    } catch {
+      parsedHost = undefined;
+    }
+    if (parsedHost !== authorityHost
+      || (!host.includes(':') && !platformDatabaseHostNamePattern.test(host))) {
+      errors.push(`${pathArg} host must be a canonical IPv4 literal, IPv6 literal without `
+        + 'brackets, or lowercase DNS name');
+    }
+  }
+  const port = valueArg.port;
+  if (typeof port !== 'number' || !Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    errors.push(`${pathArg} port must be an integer from 1 to 65535`);
+  }
+  return errors;
+};

package/ts/platform/index.ts

@@ -32,6 +32,7 @@ export {
   types,
 };
 
+export * from './database.js';
 export * from './storage.js';
 export * from './objectstorage.js';
 export * from './objectstorageenvironment.js';

package/ts/platform/objectstorageenvironment.ts

@@ -9,9 +9,12 @@ import {
   objectStorageEndpointEnvironmentKeys,
   validateObjectStorageEndpointEnvironment,
   validatePlatformObjectStorageBucketName,
+  validatePlatformObjectStorageEndpoint,
 } from './objectstorage.js';
+import type { TServiceRuntimeRefusal, TServiceRuntimeWaitingReason } from '../data/serviceruntime.js';
 import type {
   IObjectStorageRetentionEvidence,
+  IObjectStorageRetentionEvidenceExpectation,
   IObjectStorageRetentionIntent,
   TObjectStorageRetentionEnvironment,
   TObjectStorageRetentionEnvironmentKey,
@@ -20,6 +23,7 @@ import {
   createObjectStorageRetentionEnvironment,
   objectStorageRetentionEnvironmentKeys,
   validateObjectStorageRetentionEnvironment,
+  validateObjectStorageRetentionEvidence,
   validateObjectStorageRetentionIntent,
 } from './objectstorageretention.js';
 import { isPlainRecord, readDataProperties } from '../private/dataproperties.js';
@@ -45,78 +49,118 @@ 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 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.
+ * The one place a binding's environment is decided. `createObjectStorageBindingEnvironment()`
+ * throws its message, `composeObjectStorageServiceEnvironment()` reports its reason.
  */
-export const createObjectStorageBindingEnvironment = async (
+const resolveBindingEnvironment = async (
   bindingArg: IPlatformBinding,
-  endpointArg: IPlatformObjectStorageEndpoint,
-): Promise<TObjectStorageBindingEnvironment> => {
+  endpointArg: IPlatformObjectStorageEndpoint | null,
+): Promise<TBindingEnvironmentResolution> => {
   const binding = readDataProperties(bindingArg);
   if (binding === null || binding.capability !== 'objectstorage') {
-    throw new Error('objectstorage binding environment requires an objectstorage binding');
+    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) {
-    throw new Error(
-      `objectstorage binding ${bindingName} carries no canonical bucket name; Cloudly owns it and `
-        + 'no environment invents one',
-    );
+    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 endpointEnvironment;
+    return { status: 'composed', environment: 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`,
-    );
+    return { status: 'refused', reason: 'objectstorage-binding-invalid',
+      message: `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',
-    );
+    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) {
-    throw new Error('objectstorage retention evidence must use its exact schema');
+    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,
-    {
-      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,
-    },
+    expectation,
   );
-  return { ...endpointEnvironment, ...retentionEnvironment };
+  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;
 };
 
 /**
@@ -152,6 +196,16 @@ export const validateObjectStorageBindingEnvironment = async (
   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.
  *
@@ -163,14 +217,105 @@ 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',
-    );
-  }
+  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/requests/node.ts

@@ -5,6 +5,7 @@ import type { IClusterNode, INodeAction, INodeMetricsSample, TNodeActionName } f
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
 import type { IPlatformObjectStorageEndpoint } from '../platform/objectstorage.js';
+import type { IPlatformDatabaseEndpoint } from '../platform/database.js';
 import type {
   INodeCredentialMetadata,
   INodeCredentialMutationPreconditions,
@@ -315,6 +316,38 @@ export interface IReq_Any_Cloudly_SetClusterNodeCorestoreObjectStorageEndpoint e
   };
 }
 
+/**
+ * An administrator states where a workload on one node reaches the node's Corestore database:
+ * `IClusterNode.data.corestoreDatabase`.
+ *
+ * A request of its own, separate from `setClusterNodeCorestoreEndpoint` and
+ * `setClusterNodeCorestoreObjectStorageEndpoint`: each sets one fact and never touches the others.
+ *
+ * Cloudly validates it with `validatePlatformDatabaseEndpoint` before it writes and takes the
+ * node's own real-write fence inside the writing transaction, as for the other two endpoints.
+ * `database: null` clears it, which is the same fact as never having set one: no database
+ * credential can be published for a binding on this node. A changed endpoint changes the binding
+ * request of every database binding placed on the node, so each is granted and published again,
+ * addressed to the new endpoint. The endpoint says where, never with what — no credential travels
+ * in this request or in the node document.
+ */
+export interface IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_SetClusterNodeCorestoreDatabaseEndpoint
+> {
+  method: 'setClusterNodeCorestoreDatabaseEndpoint';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    /** The node's database endpoint, or `null` to state that it has none. */
+    database: IPlatformDatabaseEndpoint | 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

package/ts/runtime.corestore.ts

@@ -21,6 +21,11 @@ import {
   validateObjectStorageRetentionIntent,
 } from './platform/objectstorageretention.js';
 import { validatePlatformObjectStorageBucketName } from './platform/objectstorage.js';
+import type { IPlatformDatabaseEndpoint } from './platform/database.js';
+import {
+  formatPlatformDatabaseEndpointHost,
+  validatePlatformDatabaseEndpoint,
+} from './platform/database.js';
 import {
   canonicalizeStrictJson,
   createCanonicalJsonSha256Hex,
@@ -415,6 +420,14 @@ interface ICorestoreCredentialBindingRequestBase {
 export type TCorestoreCredentialBindingRequest =
   | ICorestoreCredentialBindingRequestBase & {
       capability: 'database';
+      /**
+       * Where a workload reaches the database: the `corestoreDatabase` of the node the binding is
+       * placed on. Corestore addresses the binding's connection values to it, and it is part of
+       * the request digest, so a changed endpoint is a changed request that is granted and
+       * published again. A request without it names no address a workload can reach; whether one
+       * is admitted is the provider's decision, never a default this contract supplies.
+       */
+      endpoint?: IPlatformDatabaseEndpoint;
     }
   | ICorestoreCredentialBindingRequestBase & {
       capability: 'objectstorage';
@@ -441,7 +454,7 @@ export const validateCorestoreCredentialBindingRequest = (
     'environment',
   ];
   if (requestArg.capability === 'database') {
-    if (!hasExactKeys(requestArg, baseKeys)) {
+    if (!hasExactKeys(requestArg, baseKeys, ['endpoint'])) {
       return ['corestore database credential binding request must use its exact schema'];
     }
   } else if (requestArg.capability === 'objectstorage') {
@@ -462,6 +475,12 @@ export const validateCorestoreCredentialBindingRequest = (
     || requestArg.environment !== corestoreCredentialEnvironment) {
     errors.push('corestore credential binding request constants must be canonical');
   }
+  if (requestArg.capability === 'database' && requestArg.endpoint !== undefined) {
+    errors.push(...validatePlatformDatabaseEndpoint(
+      requestArg.endpoint,
+      'corestore database credential binding request endpoint',
+    ));
+  }
   if (requestArg.capability === 'objectstorage') {
     errors.push(...validatePlatformObjectStorageBucketName(
       requestArg.bucketName,
@@ -489,6 +508,9 @@ export const createCorestoreCredentialBindingRequestDigestInput = (
     providerConfigId: requestArg.providerConfigId,
     managementScope: requestArg.managementScope,
     environment: requestArg.environment,
+    ...(requestArg.capability === 'database' && requestArg.endpoint
+      ? { endpoint: { host: requestArg.endpoint.host, port: requestArg.endpoint.port } }
+      : {}),
     ...(requestArg.capability === 'objectstorage'
       ? {
           bucketName: requestArg.bucketName,
@@ -727,6 +749,91 @@ export const validateCorestoreDatabaseCredentialMaterial = (
   return errors;
 };
 
+/** What a database binding's connection values are made of, besides where the database is. */
+export interface ICorestoreDatabaseCredentialIdentity {
+  databaseName: string;
+  username: string;
+  password: string;
+}
+
+/**
+ * The connection URI of one database binding, addressed to `endpointArg`:
+ * `mongodb://<username>:<password>@<host>:<port>/<databaseName>?authSource=<databaseName>&directConnection=true`,
+ * the username, password and database name URI-component encoded, an IPv6 host in brackets.
+ * This is the one form Corestore writes and Cloudly checks, so the two can never disagree.
+ */
+export const createCorestoreDatabaseUri = (
+  endpointArg: IPlatformDatabaseEndpoint,
+  identityArg: ICorestoreDatabaseCredentialIdentity,
+): string => {
+  const endpointErrors = validatePlatformDatabaseEndpoint(endpointArg);
+  if (endpointErrors.length > 0) throw new Error(endpointErrors[0]);
+  const query = new URLSearchParams({
+    authSource: identityArg.databaseName,
+    directConnection: 'true',
+  });
+  return `mongodb://${encodeURIComponent(identityArg.username)}:`
+    + `${encodeURIComponent(identityArg.password)}@`
+    + `${formatPlatformDatabaseEndpointHost(endpointArg.host)}:${endpointArg.port}`
+    + `/${encodeURIComponent(identityArg.databaseName)}?${query.toString()}`;
+};
+
+/**
+ * The eleven connection values of one database binding, addressed to `endpointArg`: the three URI
+ * aliases from `createCorestoreDatabaseUri()`, `MONGODB_HOST` the endpoint host without brackets,
+ * `MONGODB_PORT` its port in decimal, and the database, username and password under both alias
+ * families. Throws the first reason the result would not be valid material; nothing is defaulted.
+ */
+export const createCorestoreDatabaseCredentialValues = (
+  endpointArg: IPlatformDatabaseEndpoint,
+  identityArg: ICorestoreDatabaseCredentialIdentity,
+): TCorestoreDatabaseCredentialValues => {
+  const uri = createCorestoreDatabaseUri(endpointArg, identityArg);
+  const values: TCorestoreDatabaseCredentialValues = {
+    MONGODB_URI: uri,
+    MONGODB_URL: uri,
+    MONGO_URL: uri,
+    MONGODB_HOST: endpointArg.host,
+    MONGODB_PORT: String(endpointArg.port),
+    MONGODB_DATABASE: identityArg.databaseName,
+    MONGO_DBNAME: identityArg.databaseName,
+    MONGODB_USERNAME: identityArg.username,
+    MONGO_DBUSER: identityArg.username,
+    MONGODB_PASSWORD: identityArg.password,
+    MONGO_DBPASS: identityArg.password,
+  };
+  const errors = validateCorestoreDatabaseCredentialMaterial({ capability: 'database', values });
+  if (errors.length > 0) throw new Error(errors[0]);
+  return values;
+};
+
+/**
+ * Validates database material and that it is addressed to `endpointArg`: every value is the one
+ * `createCorestoreDatabaseCredentialValues()` derives from the endpoint and the material's own
+ * database name, username and password. Material a provider addressed to any other host or port —
+ * its own public host above all — is refused by name.
+ */
+export const validateCorestoreDatabaseCredentialMaterialEndpoint = (
+  materialArg: unknown,
+  endpointArg: IPlatformDatabaseEndpoint,
+): string[] => {
+  const errors = validateCorestoreDatabaseCredentialMaterial(materialArg);
+  if (errors.length > 0) return errors;
+  const endpointErrors = validatePlatformDatabaseEndpoint(endpointArg);
+  if (endpointErrors.length > 0) return endpointErrors;
+  const values = (materialArg as ICorestoreDatabaseCredentialPlaintextMaterial).values;
+  const expected = createCorestoreDatabaseCredentialValues(endpointArg, {
+    databaseName: values.MONGODB_DATABASE,
+    username: values.MONGODB_USERNAME,
+    password: values.MONGODB_PASSWORD,
+  });
+  const mismatched = corestoreDatabaseCredentialKeys
+    .filter((keyArg) => values[keyArg] !== expected[keyArg]);
+  return mismatched.length > 0
+    ? [`corestore database credential ${mismatched.join(', ')} must be addressed to the binding endpoint`]
+    : [];
+};
+
 export const validateCorestoreObjectStorageCredentialMaterial = async (
   materialArg: unknown,
   retentionExpectationArg?: IObjectStorageRetentionEvidenceExpectation,