@serve.zone/interfaces 32.26.0 → 32.28.0

package/ts/data/runtimelocalstorageclaim.ts

@@ -3,8 +3,10 @@ import type { IRuntimeAssignment, IRuntimeAuthorityReference, IRuntimeController
 import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
 import type { IRuntimeSessionBinding } from './runtimesession.js';
 import { snapshotRuntimeSessionBinding } from './runtimesession.js';
-import { captureNetwork, networkController, networkDigest, networkEqual, networkHash, networkId,
-  networkNodeId, networkRecord, networkReference, networkReferenceOf, networkRevision, requireNetwork,
+import type { IIdentityCredential } from './user.js';
+import { captureNetwork, networkController, networkCounter, networkDigest, networkEqual, networkHash, networkId,
+  networkList, networkNodeId, networkRecord, networkReference, networkReferenceOf, networkRevision, networkSorted,
+  requireNetwork,
 } from '../private/networkcontract.js';
 import { parseCanonicalIpAddress } from '../private/ipaddress.js';
 import { isRuntimeIdentityNumber } from '../private/runtimepolicy.js';
@@ -161,6 +163,60 @@ export interface IApplyRuntimeLocalStorageClaimResponse {
   claim: IRuntimeAuthorityReference;
 }
 
+/**
+ * What an administrator reads about one local storage claim a controller issued: where the volume
+ * is, whose it is, how it starts and what its node last answered.
+ *
+ * It is a projection of the controller's current generation, never the claim itself: it carries no
+ * digest, no controller epoch and no source beyond its kind, so an SMB claim's credential reference
+ * is not in it. `claimId` is the claim's `id`, the name the node keys the volume by, including the
+ * `import/<claimId>` directory an operator places an `import` volume's bytes in; a reader takes it
+ * from here and never derives it.
+ *
+ * `state` is what the node answered about exactly `generation`, or `null` while the node has not
+ * acknowledged that generation. It follows the rule `bindApplyRuntimeLocalStorageClaimResponse`
+ * holds an answer to: a bound claim is `ready`, `import-required` (an `import` claim only) or
+ * `uncertain`; a purge is `purged` or `uncertain`.
+ */
+export interface IRuntimeLocalStorageClaimSummary {
+  claimId: string;
+  generation: number;
+  clusterId: string;
+  nodeId: string;
+  serviceId: string;
+  volumeId: string;
+  mountPath: string;
+  sourceKind: TRuntimeLocalStorageSource['kind'];
+  initialization: IRuntimeLocalStorageClaim['initialization'];
+  lifecycle: TRuntimeLocalStorageLifecycle;
+  state: TRuntimeLocalStorageClaimState | null;
+}
+
+/**
+ * An administrator's read of the local storage claims of one cluster, optionally of one node.
+ *
+ * Paged: `cursor` is the opaque `nextCursor` of the previous page, and `limit` asks for at most that
+ * many summaries, which the controller may lower but never exceed; both absent read the first page
+ * at the controller's own size.
+ */
+export interface IGetRuntimeLocalStorageClaimsRequest {
+  /** The controller verifies this credential and derives every actor claim itself. */
+  identity: IIdentityCredential;
+  clusterId: string;
+  nodeId?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+/**
+ * One page of summaries in strictly ascending `claimId` order. `nextCursor` is omitted on the final
+ * page; a page that carries it carries at least one summary.
+ */
+export interface IGetRuntimeLocalStorageClaimsResponse {
+  claims: IRuntimeLocalStorageClaimSummary[];
+  nextCursor?: string;
+}
+
 export const runtimeLocalStorageClaimContract = Object.freeze({
   digestDomain: 'serve.zone/runtime-local-storage-claim',
   error: 'Runtime local storage claim contract rejected.',
@@ -178,6 +234,11 @@ export const runtimeLocalStorageClaimContract = Object.freeze({
   maximumSegmentLength: 255,
   /** The longest SMB share name. */
   maximumShareLength: 80,
+  /**
+   * The most claim summaries one `getRuntimeLocalStorageClaims` page carries. A page of summaries
+   * with every field at its bound stays inside the network contract's one-mebibyte capture.
+   */
+  maximumSummaryPageSize: 200,
 } as const);
 
 const fail = (): never => { throw new Error(runtimeLocalStorageClaimContract.error); };
@@ -241,6 +302,14 @@ const shareOf = (valueArg: unknown): string => {
   return valueArg;
 };
 
+/** The states a node may answer about one generation, whatever the answer's status. */
+const isClaimStateOf = (
+  claimArg: Pick<IRuntimeLocalStorageClaim, 'lifecycle' | 'initialization'>, stateArg: TRuntimeLocalStorageClaimState,
+): boolean => claimArg.lifecycle === 'purge'
+  ? stateArg === 'purged' || stateArg === 'uncertain'
+  : stateArg === 'ready' || stateArg === 'uncertain'
+    || (stateArg === 'import-required' && claimArg.initialization === 'import');
+
 const literalOf = <TLiteral extends string>(valueArg: unknown, allowedArg: readonly TLiteral[]): TLiteral => {
   requireNetwork((allowedArg as readonly unknown[]).includes(valueArg));
   return valueArg as TLiteral;
@@ -424,11 +493,107 @@ export const bindApplyRuntimeLocalStorageClaimResponse = (
   const response = snapshotApplyRuntimeLocalStorageClaimResponse(valueArg);
   const { claim } = snapshotApplyRuntimeLocalStorageClaimRequest(requestArg);
   requireNetwork(networkEqual(response.claim, getRuntimeLocalStorageClaimReference(claim)));
-  if (response.status !== 'historical') {
-    requireNetwork(claim.lifecycle === 'purge'
-      ? response.state === 'purged' || response.state === 'uncertain'
-      : response.state === 'ready' || response.state === 'uncertain'
-        || (response.state === 'import-required' && claim.initialization === 'import'));
-  }
+  if (response.status !== 'historical') requireNetwork(isClaimStateOf(claim, response.state));
+  return response;
+});
+
+const sourceKinds = ['directory', 'nfs', 'smb'] as const;
+const initializations = ['empty', 'import'] as const;
+const lifecycles = ['bound', 'purge'] as const;
+
+/** Detached exact-schema snapshot of one summary, its state judged against its lifecycle. */
+export const snapshotRuntimeLocalStorageClaimSummary = (
+  valueArg: unknown,
+): IRuntimeLocalStorageClaimSummary => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['claimId', 'generation', 'clusterId', 'nodeId',
+    'serviceId', 'volumeId', 'mountPath', 'sourceKind', 'initialization', 'lifecycle', 'state']);
+  const summary: IRuntimeLocalStorageClaimSummary = {
+    claimId: networkId(value.claimId),
+    generation: networkCounter(value.generation),
+    clusterId: networkId(value.clusterId),
+    nodeId: networkNodeId(value.nodeId),
+    serviceId: networkId(value.serviceId),
+    volumeId: networkId(value.volumeId),
+    mountPath: readMountPath(value.mountPath, 'mountPath'),
+    sourceKind: literalOf(value.sourceKind, sourceKinds),
+    initialization: literalOf(value.initialization, initializations),
+    lifecycle: literalOf(value.lifecycle, lifecycles),
+    state: value.state === null ? null : literalOf(value.state, claimStates),
+  };
+  // A purge always follows a bound generation, and an SMB volume always starts empty.
+  requireNetwork((summary.lifecycle === 'bound' || summary.generation > 1)
+    && (summary.sourceKind !== 'smb' || summary.initialization === 'empty')
+    && (summary.state === null || isClaimStateOf(summary, summary.state)));
+  return summary;
+});
+
+/**
+ * The one projection of a claim and its node's last answer into a summary. `stateArg` is what the
+ * node answered about exactly this generation, or `null` while it has not acknowledged it.
+ */
+export const summarizeRuntimeLocalStorageClaim = (
+  claimArg: unknown, stateArg: TRuntimeLocalStorageClaimState | null,
+): IRuntimeLocalStorageClaimSummary => {
+  const claim = snapshotRuntimeLocalStorageClaim(claimArg);
+  return snapshotRuntimeLocalStorageClaimSummary({
+    claimId: claim.id,
+    generation: claim.generation,
+    clusterId: claim.clusterId,
+    nodeId: claim.nodeId,
+    serviceId: claim.serviceId,
+    volumeId: claim.volumeId,
+    mountPath: claim.mount.mountPath,
+    sourceKind: claim.source.kind,
+    initialization: claim.initialization,
+    lifecycle: claim.lifecycle,
+    state: stateArg,
+  });
+};
+
+/**
+ * Detached exact-schema snapshot of a read request. It checks the identity's shape only: the
+ * controller authenticates it.
+ */
+export const snapshotGetRuntimeLocalStorageClaimsRequest = (
+  valueArg: unknown,
+): IGetRuntimeLocalStorageClaimsRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['identity', 'clusterId'], ['nodeId', 'cursor', 'limit']);
+  const identity = networkRecord(value.identity, ['jwt']);
+  requireNetwork(typeof identity.jwt === 'string' && identity.jwt.length > 0);
+  return {
+    identity: { jwt: identity.jwt as string },
+    clusterId: networkId(value.clusterId),
+    ...(Object.hasOwn(value, 'nodeId') ? { nodeId: networkNodeId(value.nodeId) } : {}),
+    ...(Object.hasOwn(value, 'cursor') ? { cursor: networkId(value.cursor) } : {}),
+    ...(Object.hasOwn(value, 'limit')
+      ? { limit: networkCounter(value.limit, runtimeLocalStorageClaimContract.maximumSummaryPageSize) } : {}),
+  };
+});
+
+/** Detached exact-schema snapshot of one page: bounded, strictly ascending and never empty with a cursor. */
+export const snapshotGetRuntimeLocalStorageClaimsResponse = (
+  valueArg: unknown,
+): IGetRuntimeLocalStorageClaimsResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['claims'], ['nextCursor']);
+  const claims = networkList(value.claims, runtimeLocalStorageClaimContract.maximumSummaryPageSize,
+    snapshotRuntimeLocalStorageClaimSummary);
+  networkSorted(claims, (claimArg) => claimArg.claimId);
+  if (!Object.hasOwn(value, 'nextCursor')) return { claims };
+  requireNetwork(claims.length > 0);
+  return { claims, nextCursor: networkId(value.nextCursor) };
+});
+
+/**
+ * Matches a page to the read that asked for it: every summary names the requested cluster and, when
+ * the request named one, the requested node, and the page holds no more than the requested `limit`.
+ */
+export const bindGetRuntimeLocalStorageClaimsResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IGetRuntimeLocalStorageClaimsResponse => safe(() => {
+  const response = snapshotGetRuntimeLocalStorageClaimsResponse(valueArg);
+  const request = snapshotGetRuntimeLocalStorageClaimsRequest(requestArg);
+  requireNetwork(response.claims.length <= (request.limit ?? runtimeLocalStorageClaimContract.maximumSummaryPageSize)
+    && response.claims.every((claimArg) => claimArg.clusterId === request.clusterId
+      && (request.nodeId === undefined || claimArg.nodeId === request.nodeId)));
   return response;
 });

package/ts/data/serviceruntime.ts

@@ -89,6 +89,7 @@ const serviceRuntimeRefusals = [
   'volume-driver-unsupported', 'volume-options-unsupported', 'volume-shared-unsupported',
   'volume-placement-unsupported', 'volume-initialization-unknown', 'volume-ownership-unknown',
   'objectstorage-endpoint-missing', 'objectstorage-binding-invalid', 'objectstorage-environment-conflict',
+  'database-endpoint-missing',
 ] as const;
 
 /**
@@ -128,6 +129,10 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * states no valid `corestoreObjectStorage`, `objectstorage-binding-invalid` a binding
  * `createObjectStorageBindingEnvironment` refuses, and `objectstorage-environment-conflict` a name
  * the service's own environment or another binding already sets.
+ *
+ * `database-endpoint-missing` is an enabled database binding placed on a node that states no valid
+ * `corestoreDatabase`: its credential cannot be addressed to any host a workload reaches, so it is
+ * neither granted nor published, and the workload is not started with a guessed one.
  */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];
 

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/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/requests/runtimesession.ts

@@ -179,6 +179,22 @@ export interface IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim extends pl
   response: localStorage.IApplyRuntimeLocalStorageClaimResponse;
 }
 
+/**
+ * An administrator reads the local storage claims Cloudly issued in one cluster, optionally on one
+ * node, one page at a time: each claim's id, volume, mount path, initialization, lifecycle and what
+ * its node last answered. `snapshotGetRuntimeLocalStorageClaimsRequest` and
+ * `bindGetRuntimeLocalStorageClaimsResponse` judge both sides; a summary never carries the claim's
+ * source beyond its kind, so no credential reference leaves Cloudly through it.
+ */
+export interface IReq_Any_Cloudly_GetRuntimeLocalStorageClaims extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetRuntimeLocalStorageClaims
+> {
+  method: 'getRuntimeLocalStorageClaims';
+  request: localStorage.IGetRuntimeLocalStorageClaimsRequest;
+  response: localStorage.IGetRuntimeLocalStorageClaimsResponse;
+}
+
 /** Current-peer report, including exact historical outbox recovery after reconnect. */
 export interface IReq_Pallet_Controller_ReportRuntimeAssignmentObservation extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,

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,