@serve.zone/interfaces 25.1.1 → 25.3.0

package/ts/runtime.corestore.ts

@@ -0,0 +1,909 @@
+import * as plugins from './plugins.js';
+import type {
+  IActiveSecretRecipientMetadata,
+  IIdentityCredential,
+  ISecretVersionReference,
+} from './data/index.js';
+import { isSha256Digest } from './data/immutableimage.js';
+import {
+  validateSecretRecipientMetadata,
+  verifySecretEnvelopeContext,
+} from './data/secret.js';
+import type { ISecretEnvelopeAdmissionBindingV1 } from './runtime.js';
+import type {
+  IObjectStorageRetentionEvidenceExpectationV1,
+  IObjectStorageRetentionEvidenceV1,
+} from './platform/objectstorageretention.js';
+import { validateObjectStorageRetentionEvidence } from './platform/objectstorageretention.js';
+
+export type TCorestoreCredentialCapability = 'database' | 'objectstorage';
+
+export const corestoreProviderConfigIds = Object.freeze({
+  database: 'cloudly-corestore-database',
+  objectstorage: 'cloudly-corestore-objectstorage',
+} as const);
+export const corestoreControlUrl = 'http://corestore:3000' as const;
+export const corestoreCredentialManagementScope = 'platform:cloudly-corestore' as const;
+export const corestoreControlCredentialKey = 'CORESTORE_API_TOKEN' as const;
+export const corestoreCredentialEnvironment = 'production' as const;
+
+export const corestoreCredentialRuntimeLimits = Object.freeze({
+  maximumIdentifierLength: 200,
+  maximumPublicationGrants: 256,
+  maximumGrantLifetimeMs: 24 * 60 * 60 * 1000,
+  maximumCredentialStringBytes: 8 * 1024,
+  maximumSealedMaterialBytes: 64 * 1024,
+  minimumControlTokenBytes: 32,
+  maximumControlTokenBytes: 4096,
+  maximumSealedControlCredentialBytes: 12 * 1024,
+});
+
+export const getCorestoreProviderConfigId = (
+  capabilityArg: TCorestoreCredentialCapability,
+): typeof corestoreProviderConfigIds[TCorestoreCredentialCapability] => {
+  if (capabilityArg !== 'database' && capabilityArg !== 'objectstorage') {
+    throw new Error('corestore capability must be database or objectstorage');
+  }
+  return corestoreProviderConfigIds[capabilityArg];
+};
+
+export interface ICorestoreControlCredentialPlaintextV1 {
+  schemaVersion: 1;
+  key: typeof corestoreControlCredentialKey;
+  environment: typeof corestoreCredentialEnvironment;
+  value: string;
+}
+
+export interface ICorestoreControlCredentialMaterialV1 {
+  schemaVersion: 1;
+  requestId: string;
+  clusterId: string;
+  capability: TCorestoreCredentialCapability;
+  providerConfigId: typeof corestoreProviderConfigIds[TCorestoreCredentialCapability];
+  controlUrl: typeof corestoreControlUrl;
+  managementScope: typeof corestoreCredentialManagementScope;
+  key: typeof corestoreControlCredentialKey;
+  environment: typeof corestoreCredentialEnvironment;
+  recipientKeyId: string;
+  recipientGeneration: number;
+  envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+}
+
+export interface IReq_GetCorestoreControlCredentialMaterial
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetCorestoreControlCredentialMaterial
+> {
+  method: 'getCorestoreControlCredentialMaterial';
+  request: {
+    identity: IIdentityCredential;
+    requestId: string;
+    capability: TCorestoreCredentialCapability;
+    expectedRecipientKeyId: string;
+    expectedRecipientGeneration: number;
+  };
+  response: {
+    material: ICorestoreControlCredentialMaterialV1;
+  };
+}
+
+export interface ICorestoreControlCredentialMaterialExpectationV1 {
+  requestId: string;
+  clusterId: string;
+  capability: TCorestoreCredentialCapability;
+  expectedRecipientKeyId: string;
+  expectedRecipientGeneration: number;
+}
+
+export interface ICorestoreControlCredentialMaterialContextInputV1 {
+  requestId: string;
+  clusterId: string;
+  capability: TCorestoreCredentialCapability;
+  recipientKeyId: string;
+  recipientGeneration: number;
+}
+
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const bareSha256Pattern = /^[a-f0-9]{64}$/;
+const environmentKeyPattern = /^[A-Z_][A-Z0-9_]{0,127}$/;
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  Boolean(valueArg)
+  && typeof valueArg === 'object'
+  && !Array.isArray(valueArg)
+  && (Object.getPrototypeOf(valueArg) === Object.prototype
+    || Object.getPrototypeOf(valueArg) === null)
+);
+
+const hasExactKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+): boolean => {
+  const actual = Object.keys(valueArg).sort();
+  const expected = [...keysArg].sort();
+  return actual.length === expected.length
+    && actual.every((keyArg, indexArg) => keyArg === expected[indexArg]);
+};
+
+const hasKeys = (
+  valueArg: Record<string, unknown>,
+  requiredArg: readonly string[],
+  optionalArg: readonly string[],
+): boolean => requiredArg.every((keyArg) => Object.hasOwn(valueArg, keyArg))
+  && Object.keys(valueArg).every((keyArg) => requiredArg.includes(keyArg)
+    || optionalArg.includes(keyArg));
+
+const isIdentifier = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && identifierPattern.test(valueArg)
+);
+
+const isPositiveSafeInteger = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) > 0
+);
+
+const isNonNegativeSafeInteger = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) >= 0 && !Object.is(valueArg, -0)
+);
+
+const isJwtIdentity = (valueArg: unknown): valueArg is IIdentityCredential => (
+  isRecord(valueArg)
+  && hasExactKeys(valueArg, ['jwt'])
+  && typeof valueArg.jwt === 'string'
+  && valueArg.jwt.length > 0
+);
+
+const utf8ByteLength = (valueArg: string): number => new TextEncoder().encode(valueArg).byteLength;
+
+const isCorestoreControlToken = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0 || /\s/u.test(valueArg)) return false;
+  const encoded = new TextEncoder().encode(valueArg);
+  let roundTrip: string;
+  try {
+    roundTrip = new TextDecoder('utf-8', { fatal: true }).decode(encoded);
+  } catch {
+    return false;
+  }
+  return roundTrip === valueArg
+    && encoded.byteLength >= corestoreCredentialRuntimeLimits.minimumControlTokenBytes
+    && encoded.byteLength <= corestoreCredentialRuntimeLimits.maximumControlTokenBytes;
+};
+
+export const validateGetCorestoreControlCredentialMaterialRequest = (
+  requestArg: unknown,
+  activeRecipientArg: IActiveSecretRecipientMetadata,
+): string[] => {
+  if (!isRecord(requestArg)
+    || !hasExactKeys(requestArg, [
+      'identity',
+      'requestId',
+      'capability',
+      'expectedRecipientKeyId',
+      'expectedRecipientGeneration',
+    ])) {
+    return ['corestore control credential request must use its exact schema'];
+  }
+  const errors: string[] = [];
+  if (!isJwtIdentity(requestArg.identity)) {
+    errors.push('corestore control credential request requires only a JWT identity');
+  }
+  if (!isIdentifier(requestArg.requestId)
+    || !isIdentifier(requestArg.expectedRecipientKeyId)) {
+    errors.push('corestore control credential request identifiers must be canonical');
+  }
+  if (requestArg.capability !== 'database' && requestArg.capability !== 'objectstorage') {
+    errors.push('corestore control credential capability must be database or objectstorage');
+  }
+  if (!isPositiveSafeInteger(requestArg.expectedRecipientGeneration)) {
+    errors.push('corestore control credential recipient generation must be positive');
+  }
+  if (validateSecretRecipientMetadata(activeRecipientArg).length > 0
+    || activeRecipientArg.lifecycleState !== 'active'
+    || requestArg.expectedRecipientKeyId !== activeRecipientArg.recipientKeyId
+    || requestArg.expectedRecipientGeneration !== activeRecipientArg.generation) {
+    errors.push('corestore control credential request must target the active recipient');
+  }
+  return errors;
+};
+
+export const createCorestoreControlCredentialMaterialEnvelopeContext = (
+  materialArg: ICorestoreControlCredentialMaterialContextInputV1,
+): Uint8Array => new TextEncoder().encode(JSON.stringify({
+  schemaVersion: 1,
+  purpose: 'serve.zone/corestore-control-credential-material',
+  requestId: materialArg.requestId,
+  clusterId: materialArg.clusterId,
+  capability: materialArg.capability,
+  providerConfigId: getCorestoreProviderConfigId(materialArg.capability),
+  controlUrl: corestoreControlUrl,
+  managementScope: corestoreCredentialManagementScope,
+  key: corestoreControlCredentialKey,
+  environment: corestoreCredentialEnvironment,
+  recipientKeyId: materialArg.recipientKeyId,
+  recipientGeneration: materialArg.recipientGeneration,
+}));
+
+export const validateCorestoreControlCredentialPlaintext = (
+  plaintextArg: unknown,
+): string[] => {
+  if (!isRecord(plaintextArg)
+    || !hasExactKeys(plaintextArg, ['schemaVersion', 'key', 'environment', 'value'])) {
+    return ['corestore control credential plaintext must use its exact schema'];
+  }
+  const errors: string[] = [];
+  if (plaintextArg.schemaVersion !== 1
+    || plaintextArg.key !== corestoreControlCredentialKey
+    || plaintextArg.environment !== corestoreCredentialEnvironment) {
+    errors.push('corestore control credential plaintext constants must be canonical');
+  }
+  if (!isCorestoreControlToken(plaintextArg.value)) {
+    errors.push('corestore control credential value must be 32-4096 UTF-8 bytes without whitespace');
+  }
+  return errors;
+};
+
+export const validateCorestoreControlCredentialMaterial = async (
+  materialArg: unknown,
+  expectedArg: ICorestoreControlCredentialMaterialExpectationV1,
+): Promise<string[]> => {
+  if (!isRecord(materialArg)
+    || !hasExactKeys(materialArg, [
+      'schemaVersion',
+      'requestId',
+      'clusterId',
+      'capability',
+      'providerConfigId',
+      'controlUrl',
+      'managementScope',
+      'key',
+      'environment',
+      'recipientKeyId',
+      'recipientGeneration',
+      'envelope',
+    ])) {
+    return ['corestore control credential material must use its exact schema'];
+  }
+  const errors: string[] = [];
+  if (materialArg.schemaVersion !== 1
+    || !isIdentifier(materialArg.requestId)
+    || !isIdentifier(materialArg.clusterId)
+    || !isIdentifier(materialArg.recipientKeyId)
+    || !isPositiveSafeInteger(materialArg.recipientGeneration)) {
+    errors.push('corestore control credential material metadata must be canonical');
+  }
+  if (materialArg.capability !== 'database' && materialArg.capability !== 'objectstorage') {
+    errors.push('corestore control credential material capability must be canonical');
+  } else if (materialArg.providerConfigId !== getCorestoreProviderConfigId(materialArg.capability)) {
+    errors.push('corestore control credential provider must be derived from capability');
+  }
+  if (materialArg.controlUrl !== corestoreControlUrl
+    || materialArg.managementScope !== corestoreCredentialManagementScope
+    || materialArg.key !== corestoreControlCredentialKey
+    || materialArg.environment !== corestoreCredentialEnvironment) {
+    errors.push('corestore control credential material constants must be canonical');
+  }
+  if (materialArg.requestId !== expectedArg.requestId
+    || materialArg.clusterId !== expectedArg.clusterId
+    || materialArg.capability !== expectedArg.capability
+    || materialArg.recipientKeyId !== expectedArg.expectedRecipientKeyId
+    || materialArg.recipientGeneration !== expectedArg.expectedRecipientGeneration) {
+    errors.push('corestore control credential material does not match its request authority');
+  }
+  let envelope: plugins.smartcrypto.IX25519EnvelopeV1 | undefined;
+  try {
+    envelope = plugins.smartcrypto.parseX25519Envelope(materialArg.envelope);
+    if (envelope.ciphertext.length
+      > Math.ceil(corestoreCredentialRuntimeLimits.maximumSealedControlCredentialBytes * 4 / 3)) {
+      errors.push('corestore control credential envelope exceeds its byte limit');
+    }
+  } catch {
+    errors.push('corestore control credential envelope must be strict');
+  }
+  if (envelope) {
+    if (envelope.recipientKeyId !== materialArg.recipientKeyId) {
+      errors.push('corestore control credential envelope recipient must match');
+    } else if (errors.length === 0 && !await verifySecretEnvelopeContext(
+      envelope,
+      createCorestoreControlCredentialMaterialEnvelopeContext(
+        materialArg as unknown as ICorestoreControlCredentialMaterialContextInputV1,
+      ),
+    )) {
+      errors.push('corestore control credential envelope context must match');
+    }
+  }
+  return errors;
+};
+
+export interface ICorestoreCredentialPublicationGrantV1 {
+  schemaVersion: 1;
+  operationId: string;
+  serviceId: string;
+  bindingId: string;
+  capability: TCorestoreCredentialCapability;
+  reconciliationGeneration: number;
+  expectedTargetSecretsRevision: number;
+  bindingRequestDigest: string;
+  issuedAt: number;
+  expiresAt: number;
+}
+
+export const validateCorestoreCredentialPublicationGrant = (
+  grantArg: unknown,
+  trustedNowArg?: number,
+): string[] => {
+  if (!isRecord(grantArg)
+    || !hasExactKeys(grantArg, [
+      'schemaVersion',
+      'operationId',
+      'serviceId',
+      'bindingId',
+      'capability',
+      'reconciliationGeneration',
+      'expectedTargetSecretsRevision',
+      'bindingRequestDigest',
+      'issuedAt',
+      'expiresAt',
+    ])) {
+    return ['corestore credential publication grant must use its exact schema'];
+  }
+  const errors: string[] = [];
+  if (grantArg.schemaVersion !== 1) {
+    errors.push('corestore credential publication grant schemaVersion must be 1');
+  }
+  if (!isIdentifier(grantArg.operationId)
+    || !isIdentifier(grantArg.serviceId)
+    || !isIdentifier(grantArg.bindingId)) {
+    errors.push('corestore credential publication grant identifiers must be canonical');
+  }
+  if (grantArg.capability !== 'database' && grantArg.capability !== 'objectstorage') {
+    errors.push('corestore credential publication grant capability must be canonical');
+  }
+  if (!isPositiveSafeInteger(grantArg.reconciliationGeneration)
+    || !isNonNegativeSafeInteger(grantArg.expectedTargetSecretsRevision)) {
+    errors.push('corestore credential publication grant revisions must be canonical');
+  }
+  if (typeof grantArg.bindingRequestDigest !== 'string'
+    || !bareSha256Pattern.test(grantArg.bindingRequestDigest)) {
+    errors.push('corestore credential publication grant digest must be bare lowercase 64-hex');
+  }
+  if (!isPositiveSafeInteger(grantArg.issuedAt)
+    || !isPositiveSafeInteger(grantArg.expiresAt)
+    || (grantArg.expiresAt as number) <= (grantArg.issuedAt as number)
+    || (grantArg.expiresAt as number) - (grantArg.issuedAt as number)
+      > corestoreCredentialRuntimeLimits.maximumGrantLifetimeMs) {
+    errors.push('corestore credential publication grant lifetime must be positive and bounded');
+  }
+  if (trustedNowArg !== undefined
+    && (!isPositiveSafeInteger(trustedNowArg)
+      || trustedNowArg < (grantArg.issuedAt as number)
+      || trustedNowArg >= (grantArg.expiresAt as number))) {
+    errors.push('corestore credential publication grant must be currently valid');
+  }
+  return errors;
+};
+
+export const corestoreCredentialPublicationGrantsEqual = (
+  leftArg: unknown,
+  rightArg: unknown,
+): boolean => validateCorestoreCredentialPublicationGrant(leftArg).length === 0
+  && validateCorestoreCredentialPublicationGrant(rightArg).length === 0
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).schemaVersion
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).schemaVersion
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).operationId
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).operationId
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).serviceId
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).serviceId
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).bindingId
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).bindingId
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).capability
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).capability
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).reconciliationGeneration
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).reconciliationGeneration
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).expectedTargetSecretsRevision
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).expectedTargetSecretsRevision
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).bindingRequestDigest
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).bindingRequestDigest
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).issuedAt
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).issuedAt
+  && (leftArg as ICorestoreCredentialPublicationGrantV1).expiresAt
+    === (rightArg as ICorestoreCredentialPublicationGrantV1).expiresAt;
+
+const comparePublicationGrants = (
+  leftArg: ICorestoreCredentialPublicationGrantV1,
+  rightArg: ICorestoreCredentialPublicationGrantV1,
+): number => leftArg.bindingId < rightArg.bindingId
+  ? -1
+  : leftArg.bindingId > rightArg.bindingId
+    ? 1
+    : leftArg.operationId < rightArg.operationId
+      ? -1
+      : leftArg.operationId > rightArg.operationId
+        ? 1
+        : 0;
+
+export const validateCorestoreCredentialPublicationGrants = (
+  grantsArg: unknown,
+  trustedNowArg?: number,
+): string[] => {
+  if (!Array.isArray(grantsArg)
+    || grantsArg.length > corestoreCredentialRuntimeLimits.maximumPublicationGrants) {
+    return ['corestore credential publication grants must be a bounded array'];
+  }
+  const errors: string[] = [];
+  let previous: ICorestoreCredentialPublicationGrantV1 | undefined;
+  for (const [index, grantArg] of grantsArg.entries()) {
+    const grantErrors = validateCorestoreCredentialPublicationGrant(grantArg, trustedNowArg);
+    errors.push(...grantErrors.map((errorArg) => `publication grants[${index}] ${errorArg}`));
+    if (grantErrors.length === 0) {
+      const grant = grantArg as ICorestoreCredentialPublicationGrantV1;
+      if (previous && comparePublicationGrants(previous, grant) >= 0) {
+        errors.push('corestore credential publication grants must be unique and sorted by bindingId then operationId');
+      }
+      previous = grant;
+    }
+  }
+  return errors;
+};
+
+export const corestoreDatabaseCredentialKeys = Object.freeze([
+  'MONGODB_URI',
+  'MONGODB_URL',
+  'MONGO_URL',
+  'MONGODB_HOST',
+  'MONGODB_PORT',
+  'MONGODB_DATABASE',
+  'MONGO_DBNAME',
+  'MONGODB_USERNAME',
+  'MONGO_DBUSER',
+  'MONGODB_PASSWORD',
+  'MONGO_DBPASS',
+] as const);
+export const corestoreObjectStorageCredentialKeys = Object.freeze([
+  'accessKeyId',
+  'secretAccessKey',
+] as const);
+
+export type TCorestoreDatabaseCredentialKey = typeof corestoreDatabaseCredentialKeys[number];
+export type TCorestoreObjectStorageCredentialKey =
+  typeof corestoreObjectStorageCredentialKeys[number];
+export type TCorestoreCredentialKey =
+  | TCorestoreDatabaseCredentialKey
+  | TCorestoreObjectStorageCredentialKey;
+
+export type TCorestoreDatabaseCredentialValuesV1 = {
+  [TKey in TCorestoreDatabaseCredentialKey]: string;
+};
+
+export interface ICorestoreDatabaseCredentialPlaintextMaterialV1 {
+  schemaVersion: 1;
+  capability: 'database';
+  values: TCorestoreDatabaseCredentialValuesV1;
+}
+
+export interface ICorestoreObjectStorageCredentialPlaintextMaterialV1 {
+  schemaVersion: 1;
+  capability: 'objectstorage';
+  values: {
+    accessKeyId: string;
+    secretAccessKey: string;
+  };
+  retention?: IObjectStorageRetentionEvidenceV1;
+}
+
+export type TCorestoreCredentialPlaintextMaterialV1 =
+  | ICorestoreDatabaseCredentialPlaintextMaterialV1
+  | ICorestoreObjectStorageCredentialPlaintextMaterialV1;
+
+const readCredentialString = (valueArg: unknown): boolean => typeof valueArg === 'string'
+  && valueArg.length > 0
+  && utf8ByteLength(valueArg) <= corestoreCredentialRuntimeLimits.maximumCredentialStringBytes
+  && !valueArg.includes('\0');
+
+export const validateCorestoreDatabaseCredentialMaterial = (
+  materialArg: unknown,
+): string[] => {
+  if (!isRecord(materialArg)
+    || !hasExactKeys(materialArg, ['schemaVersion', 'capability', 'values'])
+    || materialArg.schemaVersion !== 1
+    || materialArg.capability !== 'database'
+    || !isRecord(materialArg.values)
+    || !hasExactKeys(materialArg.values, corestoreDatabaseCredentialKeys)) {
+    return ['corestore database credential material must use its exact schema'];
+  }
+  const values = materialArg.values;
+  const errors: string[] = [];
+  if (corestoreDatabaseCredentialKeys.some((keyArg) => !readCredentialString(values[keyArg]))) {
+    errors.push('corestore database credential values must be bounded non-empty strings');
+  }
+  if (values.MONGODB_URI !== values.MONGODB_URL
+    || values.MONGODB_URI !== values.MONGO_URL) {
+    errors.push('corestore database URI aliases must be equal');
+  }
+  if (values.MONGODB_DATABASE !== values.MONGO_DBNAME) {
+    errors.push('corestore database name aliases must be equal');
+  }
+  if (values.MONGODB_USERNAME !== values.MONGO_DBUSER) {
+    errors.push('corestore database username aliases must be equal');
+  }
+  if (values.MONGODB_PASSWORD !== values.MONGO_DBPASS) {
+    errors.push('corestore database password aliases must be equal');
+  }
+  if (typeof values.MONGODB_PORT !== 'string'
+    || !/^[1-9][0-9]{0,4}$/.test(values.MONGODB_PORT)
+    || Number(values.MONGODB_PORT) > 65535) {
+    errors.push('corestore database port must be canonical');
+  }
+  return errors;
+};
+
+export const validateCorestoreObjectStorageCredentialMaterial = async (
+  materialArg: unknown,
+  retentionExpectationArg?: IObjectStorageRetentionEvidenceExpectationV1,
+): Promise<string[]> => {
+  if (!isRecord(materialArg)
+    || !hasKeys(materialArg, ['schemaVersion', 'capability', 'values'], ['retention'])
+    || materialArg.schemaVersion !== 1
+    || materialArg.capability !== 'objectstorage'
+    || !isRecord(materialArg.values)
+    || !hasExactKeys(materialArg.values, corestoreObjectStorageCredentialKeys)) {
+    return ['corestore objectstorage credential material must use its exact schema'];
+  }
+  const errors: string[] = [];
+  if (!readCredentialString(materialArg.values.accessKeyId)
+    || !readCredentialString(materialArg.values.secretAccessKey)) {
+    errors.push('corestore objectstorage credential values must be bounded non-empty strings');
+  }
+  if (materialArg.retention !== undefined) {
+    if (!retentionExpectationArg) {
+      errors.push('corestore objectstorage retention evidence requires trusted binding authority');
+    } else {
+      errors.push(...await validateObjectStorageRetentionEvidence(
+        materialArg.retention,
+        retentionExpectationArg,
+      ));
+    }
+  }
+  return errors;
+};
+
+export const validateCorestoreCredentialPlaintextMaterial = async (
+  materialArg: unknown,
+  retentionExpectationArg?: IObjectStorageRetentionEvidenceExpectationV1,
+): Promise<string[]> => isRecord(materialArg) && materialArg.capability === 'database'
+  ? validateCorestoreDatabaseCredentialMaterial(materialArg)
+  : validateCorestoreObjectStorageCredentialMaterial(materialArg, retentionExpectationArg);
+
+export interface IPublishCorestoreCredentialMaterialRequestV1 {
+  identity: IIdentityCredential;
+  mutationId: string;
+  grant: ICorestoreCredentialPublicationGrantV1;
+  expectedIngressRecipientKeyId: string;
+  expectedIngressRecipientGeneration: number;
+  envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+}
+
+export interface ICorestoreCredentialSecretVersionReferenceV1
+extends ISecretVersionReference {
+  key: TCorestoreCredentialKey;
+}
+
+export interface ICorestoreCredentialPublicationCoverageV1 {
+  keys: TCorestoreCredentialKey[];
+  versionReferences: ICorestoreCredentialSecretVersionReferenceV1[];
+}
+
+export interface ICorestoreCredentialPublicationReceiptV1 {
+  schemaVersion: 1;
+  mutationId: string;
+  organizationId: string;
+  clusterId: string;
+  serviceId: string;
+  bindingId: string;
+  capability: TCorestoreCredentialCapability;
+  grant: ICorestoreCredentialPublicationGrantV1;
+  coverage: ICorestoreCredentialPublicationCoverageV1;
+  expectedTargetSecretsRevision: number;
+  targetSecretsRevision: number;
+  ingressAdmissionBinding: ISecretEnvelopeAdmissionBindingV1;
+  acceptedAt: number;
+  replayed: boolean;
+}
+
+export interface IReq_PublishCorestoreCredentialMaterial
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PublishCorestoreCredentialMaterial
+> {
+  method: 'publishCorestoreCredentialMaterial';
+  request: IPublishCorestoreCredentialMaterialRequestV1;
+  response: {
+    receipt: ICorestoreCredentialPublicationReceiptV1;
+  };
+}
+
+export const createPublishCorestoreCredentialMaterialEnvelopeContext = (
+  requestArg: Omit<IPublishCorestoreCredentialMaterialRequestV1, 'identity' | 'envelope'>,
+): Uint8Array => new TextEncoder().encode(JSON.stringify({
+  schemaVersion: 1,
+  purpose: 'serve.zone/publish-corestore-credential-material',
+  mutationId: requestArg.mutationId,
+  grant: {
+    schemaVersion: requestArg.grant.schemaVersion,
+    operationId: requestArg.grant.operationId,
+    serviceId: requestArg.grant.serviceId,
+    bindingId: requestArg.grant.bindingId,
+    capability: requestArg.grant.capability,
+    reconciliationGeneration: requestArg.grant.reconciliationGeneration,
+    expectedTargetSecretsRevision: requestArg.grant.expectedTargetSecretsRevision,
+    bindingRequestDigest: requestArg.grant.bindingRequestDigest,
+    issuedAt: requestArg.grant.issuedAt,
+    expiresAt: requestArg.grant.expiresAt,
+  },
+  expectedIngressRecipientKeyId: requestArg.expectedIngressRecipientKeyId,
+  expectedIngressRecipientGeneration: requestArg.expectedIngressRecipientGeneration,
+}));
+
+export const validatePublishCorestoreCredentialMaterialRequest = async (
+  requestArg: unknown,
+  expectedGrantArg: ICorestoreCredentialPublicationGrantV1,
+  activeRecipientArg: IActiveSecretRecipientMetadata,
+  trustedNowArg: number,
+): Promise<string[]> => {
+  if (!isRecord(requestArg)
+    || !hasExactKeys(requestArg, [
+      'identity',
+      'mutationId',
+      'grant',
+      'expectedIngressRecipientKeyId',
+      'expectedIngressRecipientGeneration',
+      'envelope',
+    ])) {
+    return ['publish corestore credential request must use its exact schema'];
+  }
+  const errors = validateCorestoreCredentialPublicationGrant(requestArg.grant, trustedNowArg);
+  if (!corestoreCredentialPublicationGrantsEqual(requestArg.grant, expectedGrantArg)) {
+    errors.push('publish corestore credential request grant must match current server authority');
+  }
+  if (!isJwtIdentity(requestArg.identity)) {
+    errors.push('publish corestore credential request requires only a JWT identity');
+  }
+  if (!isIdentifier(requestArg.mutationId)
+    || !isIdentifier(requestArg.expectedIngressRecipientKeyId)
+    || !isPositiveSafeInteger(requestArg.expectedIngressRecipientGeneration)) {
+    errors.push('publish corestore credential request recipient and mutation must be canonical');
+  }
+  let envelope: plugins.smartcrypto.IX25519EnvelopeV1 | undefined;
+  try {
+    envelope = plugins.smartcrypto.parseX25519Envelope(requestArg.envelope);
+    if (envelope.ciphertext.length
+      > Math.ceil(corestoreCredentialRuntimeLimits.maximumSealedMaterialBytes * 4 / 3)) {
+      errors.push('publish corestore credential envelope exceeds its byte limit');
+    }
+  } catch {
+    errors.push('publish corestore credential envelope must be strict');
+  }
+  if (validateSecretRecipientMetadata(activeRecipientArg).length > 0
+    || activeRecipientArg.lifecycleState !== 'active'
+    || activeRecipientArg.recipientKeyId !== requestArg.expectedIngressRecipientKeyId
+    || activeRecipientArg.generation !== requestArg.expectedIngressRecipientGeneration) {
+    errors.push('publish corestore credential request must target the active ingress recipient');
+  }
+  if (envelope) {
+    if (envelope.recipientKeyId !== requestArg.expectedIngressRecipientKeyId) {
+      errors.push('publish corestore credential envelope recipient must match');
+    } else if (errors.length === 0 && !await verifySecretEnvelopeContext(
+      envelope,
+      createPublishCorestoreCredentialMaterialEnvelopeContext(
+        requestArg as unknown as Omit<
+          IPublishCorestoreCredentialMaterialRequestV1,
+          'identity' | 'envelope'
+        >,
+      ),
+    )) {
+      errors.push('publish corestore credential envelope context must match');
+    }
+  }
+  return errors;
+};
+
+const expectedCoverageKeys = (
+  capabilityArg: TCorestoreCredentialCapability,
+): readonly TCorestoreCredentialKey[] => capabilityArg === 'database'
+  ? corestoreDatabaseCredentialKeys
+  : corestoreObjectStorageCredentialKeys;
+
+export interface ICorestoreCredentialPublicationReceiptExpectationV1 {
+  request: IPublishCorestoreCredentialMaterialRequestV1;
+  organizationId: string;
+  clusterId: string;
+}
+
+const computeRuntimeSha256 = async (valueArg: Uint8Array): Promise<string> => {
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(
+    'SHA-256',
+    new Uint8Array(valueArg),
+  ));
+  return [...digest].map((byteArg) => byteArg.toString(16).padStart(2, '0')).join('');
+};
+
+const verifyPublicationAdmissionBinding = async (
+  bindingArg: ISecretEnvelopeAdmissionBindingV1,
+  envelopeArg: unknown,
+  contextArg: Uint8Array,
+): Promise<boolean> => {
+  try {
+    const envelope = plugins.smartcrypto.parseX25519Envelope(envelopeArg);
+    if (envelope.recipientKeyId !== bindingArg.recipientKeyId
+      || !await verifySecretEnvelopeContext(envelope, contextArg)) {
+      return false;
+    }
+    const envelopeDigestInput = JSON.stringify({
+      schemaVersion: envelope.schemaVersion,
+      profile: envelope.profile,
+      recipientKeyId: envelope.recipientKeyId,
+      ephemeralPublicKey: envelope.ephemeralPublicKey,
+      nonce: envelope.nonce,
+      ciphertext: envelope.ciphertext,
+      tag: envelope.tag,
+      contextDigest: envelope.contextDigest,
+    });
+    return bindingArg.envelopeDigest
+        === `sha256:${await computeRuntimeSha256(new TextEncoder().encode(envelopeDigestInput))}`
+      && bindingArg.requestContextDigest
+        === `sha256:${await computeRuntimeSha256(contextArg)}`;
+  } catch {
+    return false;
+  }
+};
+
+export const validateCorestoreCredentialPublicationReceipt = async (
+  receiptArg: unknown,
+  expectedArg: ICorestoreCredentialPublicationReceiptExpectationV1,
+): Promise<string[]> => {
+  if (!isRecord(receiptArg)
+    || !hasExactKeys(receiptArg, [
+      'schemaVersion',
+      'mutationId',
+      'organizationId',
+      'clusterId',
+      'serviceId',
+      'bindingId',
+      'capability',
+      'grant',
+      'coverage',
+      'expectedTargetSecretsRevision',
+      'targetSecretsRevision',
+      'ingressAdmissionBinding',
+      'acceptedAt',
+      'replayed',
+    ])) {
+    return ['corestore credential publication receipt must use its exact schema'];
+  }
+  const errors = validateCorestoreCredentialPublicationGrant(receiptArg.grant);
+  if (receiptArg.schemaVersion !== 1
+    || !isIdentifier(receiptArg.mutationId)
+    || !isIdentifier(receiptArg.organizationId)
+    || !isIdentifier(receiptArg.clusterId)
+    || !isIdentifier(receiptArg.serviceId)
+    || !isIdentifier(receiptArg.bindingId)) {
+    errors.push('corestore credential publication receipt identifiers must be canonical');
+  }
+  const grant = receiptArg.grant as ICorestoreCredentialPublicationGrantV1;
+  if ((receiptArg.capability !== 'database' && receiptArg.capability !== 'objectstorage')
+    || receiptArg.serviceId !== grant.serviceId
+    || receiptArg.bindingId !== grant.bindingId
+    || receiptArg.capability !== grant.capability
+    || receiptArg.expectedTargetSecretsRevision !== grant.expectedTargetSecretsRevision) {
+    errors.push('corestore credential publication receipt must exactly bind its grant');
+  }
+  if (receiptArg.mutationId !== expectedArg.request.mutationId
+    || receiptArg.organizationId !== expectedArg.organizationId
+    || receiptArg.clusterId !== expectedArg.clusterId
+    || !corestoreCredentialPublicationGrantsEqual(receiptArg.grant, expectedArg.request.grant)) {
+    errors.push('corestore credential publication receipt must match its trusted request scope');
+  }
+  if (!isRecord(receiptArg.coverage)
+    || !hasExactKeys(receiptArg.coverage, ['keys', 'versionReferences'])
+    || !Array.isArray(receiptArg.coverage.keys)
+    || !Array.isArray(receiptArg.coverage.versionReferences)) {
+    errors.push('corestore credential publication coverage must use its exact schema');
+  } else if (receiptArg.capability === 'database' || receiptArg.capability === 'objectstorage') {
+    const requiredKeys = expectedCoverageKeys(receiptArg.capability);
+    if (JSON.stringify(receiptArg.coverage.keys) !== JSON.stringify(requiredKeys)
+      || receiptArg.coverage.versionReferences.length !== requiredKeys.length) {
+      errors.push('corestore credential publication coverage must be exact');
+    } else {
+      const secretIds = new Set<string>();
+      const secretVersionIds = new Set<string>();
+      for (const [index, referenceArg] of receiptArg.coverage.versionReferences.entries()) {
+        if (!isRecord(referenceArg)
+          || !hasExactKeys(referenceArg, ['key', 'secretId', 'secretVersionId'])
+          || referenceArg.key !== requiredKeys[index]
+          || !isIdentifier(referenceArg.secretId)
+          || !isIdentifier(referenceArg.secretVersionId)) {
+          errors.push('corestore credential publication version references must exactly cover keys');
+          break;
+        }
+        if (secretIds.has(referenceArg.secretId as string)
+          || secretVersionIds.has(referenceArg.secretVersionId as string)) {
+          errors.push('corestore credential publication version references must be unique');
+          break;
+        }
+        secretIds.add(referenceArg.secretId as string);
+        secretVersionIds.add(referenceArg.secretVersionId as string);
+      }
+    }
+  }
+  const referenceCount = isRecord(receiptArg.coverage)
+    && Array.isArray(receiptArg.coverage.versionReferences)
+    ? receiptArg.coverage.versionReferences.length
+    : 0;
+  if (!isNonNegativeSafeInteger(receiptArg.expectedTargetSecretsRevision)
+    || !isNonNegativeSafeInteger(receiptArg.targetSecretsRevision)
+    || receiptArg.targetSecretsRevision !== receiptArg.expectedTargetSecretsRevision + referenceCount) {
+    errors.push('corestore credential publication target Secrets revision must exactly cover created versions');
+  }
+  const admission = receiptArg.ingressAdmissionBinding;
+  if (!isRecord(admission)
+    || !hasExactKeys(admission, [
+      'schemaVersion',
+      'recipientKeyId',
+      'recipientGeneration',
+      'envelopeDigest',
+      'requestContextDigest',
+    ])
+    || admission.schemaVersion !== 1
+    || !isIdentifier(admission.recipientKeyId)
+    || !isPositiveSafeInteger(admission.recipientGeneration)
+    || typeof admission.envelopeDigest !== 'string'
+    || !isSha256Digest(admission.envelopeDigest)
+    || typeof admission.requestContextDigest !== 'string'
+    || !isSha256Digest(admission.requestContextDigest)) {
+    errors.push('corestore credential publication ingress admission binding must be canonical');
+  } else if (admission.recipientKeyId !== expectedArg.request.expectedIngressRecipientKeyId
+    || admission.recipientGeneration !== expectedArg.request.expectedIngressRecipientGeneration
+    || !await verifyPublicationAdmissionBinding(
+      admission as unknown as ISecretEnvelopeAdmissionBindingV1,
+      expectedArg.request.envelope,
+      createPublishCorestoreCredentialMaterialEnvelopeContext(expectedArg.request),
+    )) {
+    errors.push('corestore credential publication ingress admission binding must match the request');
+  }
+  if (!isPositiveSafeInteger(receiptArg.acceptedAt)
+    || receiptArg.acceptedAt < grant.issuedAt
+    || receiptArg.acceptedAt >= grant.expiresAt
+    || typeof receiptArg.replayed !== 'boolean') {
+    errors.push('corestore credential publication receipt acceptance must be canonical');
+  }
+  return errors;
+};
+
+export const corestoreCredentialPublicationErrorMetadata = Object.freeze({
+  INVALID_IDENTITY: Object.freeze({ retryable: false }),
+  INVALID_REQUEST: Object.freeze({ retryable: false }),
+  GRANT_EXPIRED: Object.freeze({ retryable: false }),
+  GRANT_SCOPE_MISMATCH: Object.freeze({ retryable: false }),
+  GRANT_REVISION_MISMATCH: Object.freeze({ retryable: true }),
+  INGRESS_RECIPIENT_MISMATCH: Object.freeze({ retryable: true }),
+  ENVELOPE_INVALID: Object.freeze({ retryable: false }),
+  MATERIAL_INVALID: Object.freeze({ retryable: false }),
+  SECRETS_REVISION_CONFLICT: Object.freeze({ retryable: true }),
+  REPLAY_CONFLICT: Object.freeze({ retryable: false }),
+  INTERNAL_ERROR: Object.freeze({ retryable: true }),
+} as const);
+
+export type TCorestoreCredentialPublicationErrorCode =
+  keyof typeof corestoreCredentialPublicationErrorMetadata;
+
+export interface ICorestoreCredentialPublicationErrorMetadataV1 {
+  schemaVersion: 1;
+  code: TCorestoreCredentialPublicationErrorCode;
+  retryable: boolean;
+}
+
+export const getCorestoreCredentialPublicationErrorMetadata = (
+  codeArg: TCorestoreCredentialPublicationErrorCode,
+): ICorestoreCredentialPublicationErrorMetadataV1 => ({
+  schemaVersion: 1,
+  code: codeArg,
+  retryable: corestoreCredentialPublicationErrorMetadata[codeArg].retryable,
+});