@serve.zone/interfaces 27.1.1 → 27.3.0

package/ts/runtime.corestore.ts

@@ -23,6 +23,7 @@ import { validatePlatformObjectStorageBucketName } from './platform/objectstorag
 import {
   canonicalizeStrictJson,
   createCanonicalJsonSha256Hex,
+  deepFreezeValue,
 } from './private/canonicaljson.js';
 
 export type TCorestoreCredentialCapability = 'database' | 'objectstorage';
@@ -44,7 +45,7 @@ export const corestoreCredentialRuntimeLimits = Object.freeze({
   maximumSealedMaterialBytes: 64 * 1024,
   minimumControlTokenBytes: 32,
   maximumControlTokenBytes: 4096,
-  maximumSealedControlCredentialBytes: 12 * 1024,
+  maximumSealedControlCredentialBytes: 32 * 1024,
 });
 
 export const getCorestoreProviderConfigId = (
@@ -163,18 +164,110 @@ const isJwtIdentity = (valueArg: unknown): valueArg is IIdentityCredential => (
 
 const utf8ByteLength = (valueArg: string): number => new TextEncoder().encode(valueArg).byteLength;
 
-const isCorestoreControlToken = (valueArg: unknown): valueArg is string => {
+const isJsonWhitespaceCodePoint = (codePointArg: number): boolean => (
+  (codePointArg >= 0x0009 && codePointArg <= 0x000d)
+  || codePointArg === 0x0020
+  || codePointArg === 0x00a0
+  || codePointArg === 0x1680
+  || (codePointArg >= 0x2000 && codePointArg <= 0x200a)
+  || codePointArg === 0x2028
+  || codePointArg === 0x2029
+  || codePointArg === 0x202f
+  || codePointArg === 0x205f
+  || codePointArg === 0x3000
+  || codePointArg === 0xfeff
+);
+
+const isCorestoreControlTokenBytes = (valueArg: Uint8Array): boolean => {
+  if (valueArg.byteLength < corestoreCredentialRuntimeLimits.minimumControlTokenBytes
+    || valueArg.byteLength > corestoreCredentialRuntimeLimits.maximumControlTokenBytes) {
+    return false;
+  }
+  for (let index = 0; index < valueArg.length;) {
+    const first = valueArg[index]!;
+    let codePoint: number;
+    if (first <= 0x7f) {
+      codePoint = first;
+      index++;
+    } else if (first >= 0xc2 && first <= 0xdf
+      && index + 1 < valueArg.length
+      && valueArg[index + 1]! >= 0x80 && valueArg[index + 1]! <= 0xbf) {
+      codePoint = ((first & 0x1f) << 6) | (valueArg[index + 1]! & 0x3f);
+      index += 2;
+    } else if (first >= 0xe0 && first <= 0xef
+      && index + 2 < valueArg.length
+      && valueArg[index + 1]! >= (first === 0xe0 ? 0xa0 : 0x80)
+      && valueArg[index + 1]! <= (first === 0xed ? 0x9f : 0xbf)
+      && valueArg[index + 2]! >= 0x80 && valueArg[index + 2]! <= 0xbf) {
+      codePoint = ((first & 0x0f) << 12)
+        | ((valueArg[index + 1]! & 0x3f) << 6)
+        | (valueArg[index + 2]! & 0x3f);
+      index += 3;
+    } else if (first >= 0xf0 && first <= 0xf4
+      && index + 3 < valueArg.length
+      && valueArg[index + 1]! >= (first === 0xf0 ? 0x90 : 0x80)
+      && valueArg[index + 1]! <= (first === 0xf4 ? 0x8f : 0xbf)
+      && valueArg[index + 2]! >= 0x80 && valueArg[index + 2]! <= 0xbf
+      && valueArg[index + 3]! >= 0x80 && valueArg[index + 3]! <= 0xbf) {
+      codePoint = ((first & 0x07) << 18)
+        | ((valueArg[index + 1]! & 0x3f) << 12)
+        | ((valueArg[index + 2]! & 0x3f) << 6)
+        | (valueArg[index + 3]! & 0x3f);
+      index += 4;
+    } else {
+      return false;
+    }
+    if (isJsonWhitespaceCodePoint(codePoint)) return false;
+  }
+  return true;
+};
+
+export 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);
+    const roundTrip = new TextDecoder('utf-8', { fatal: true }).decode(encoded);
+    return roundTrip === valueArg
+      && encoded.byteLength >= corestoreCredentialRuntimeLimits.minimumControlTokenBytes
+      && encoded.byteLength <= corestoreCredentialRuntimeLimits.maximumControlTokenBytes;
   } catch {
     return false;
+  } finally {
+    encoded.fill(0);
   }
-  return roundTrip === valueArg
-    && encoded.byteLength >= corestoreCredentialRuntimeLimits.minimumControlTokenBytes
-    && encoded.byteLength <= corestoreCredentialRuntimeLimits.maximumControlTokenBytes;
+};
+
+export const createCorestoreControlCredentialPlaintextBytes = (
+  tokenBytesArg: Uint8Array,
+): Uint8Array | undefined => {
+  if (!isCorestoreControlTokenBytes(tokenBytesArg)) return undefined;
+  const prefix = new TextEncoder().encode(
+    `{"schemaVersion":1,"key":"${corestoreControlCredentialKey}","environment":"${
+      corestoreCredentialEnvironment
+    }","value":"`,
+  );
+  const suffix = new Uint8Array([0x22, 0x7d]);
+  const escaped = new Uint8Array(prefix.length + tokenBytesArg.length * 6 + suffix.length);
+  let offset = prefix.length;
+  escaped.set(prefix);
+  for (const byte of tokenBytesArg) {
+    if (byte === 0x22 || byte === 0x5c) {
+      escaped[offset++] = 0x5c;
+      escaped[offset++] = byte;
+    } else if (byte < 0x20) {
+      escaped.set([0x5c, 0x75, 0x30, 0x30], offset);
+      offset += 4;
+      escaped[offset++] = '0123456789abcdef'.charCodeAt(byte >> 4);
+      escaped[offset++] = '0123456789abcdef'.charCodeAt(byte & 0x0f);
+    } else {
+      escaped[offset++] = byte;
+    }
+  }
+  escaped.set(suffix, offset);
+  offset += suffix.length;
+  const plaintext = escaped.slice(0, offset);
+  escaped.fill(0);
+  return plaintext;
 };
 
 export const validateGetCorestoreControlCredentialMaterialRequest = (
@@ -1174,3 +1267,610 @@ export const getCorestoreCredentialPublicationErrorMetadata = (
   code: codeArg,
   retryable: corestoreCredentialPublicationErrorMetadata[codeArg].retryable,
 });
+
+const corestoreDatabaseBackupMaximumSnapshotPayloadBytes = 96 * 1024 * 1024;
+
+export const corestoreDatabaseBackupRuntimeLimits = Object.freeze({
+  maximumControlBytes: 16 * 1024,
+  maximumClosureBytes: 256 * 1024 * 1024,
+  maximumVerifiedPlaintextBytes: 128 * 1024 * 1024,
+  maximumSnapshotPayloadBytes: corestoreDatabaseBackupMaximumSnapshotPayloadBytes,
+  maximumSnapshotOriginalBytes: corestoreDatabaseBackupMaximumSnapshotPayloadBytes + 1,
+  maximumClosureObjects: 4096,
+  maximumClosureChunks: 1_000_000,
+  maximumServiceNameBytes: 1024,
+});
+
+export interface ICorestoreDatabaseAllocationReference {
+  purpose: 'scratch-rehearsal';
+  rehearsalId: string;
+  allocationId: string;
+  generation: number;
+  bindingSha256: string;
+  receiptSha256: string;
+}
+
+export interface ICorestoreDatabaseBackupSnapshotTags {
+  corestore: 'resource';
+  serviceId: string;
+  serviceName: string;
+  capability: 'database';
+  resourceName: string;
+  snapshotName: string;
+  backupId: string;
+}
+
+export interface ICorestoreDatabaseBackupSnapshot {
+  capability: 'database';
+  resourceName: string;
+  snapshotId: string;
+  snapshotName: string;
+  originalSize: number;
+  storedSize: number;
+  createdAt: number;
+  tags: ICorestoreDatabaseBackupSnapshotTags;
+  databaseName: string;
+  databaseAllocation?: ICorestoreDatabaseAllocationReference;
+}
+
+export interface ICorestoreDatabaseBackupClosureReceipt {
+  formatVersion: 1;
+  snapshotIds: [string];
+  objectCount: number;
+  packCount: number;
+  chunkCount: number;
+  payloadBytes: number;
+  archiveBytes: number;
+  sha256: string;
+}
+
+export interface ICorestoreDatabaseBackupReceipt {
+  schemaVersion: 1;
+  format: 'corestore.database.backup.v1';
+  backupId: string;
+  sourceServiceId: string;
+  createdAt: number;
+  snapshot: ICorestoreDatabaseBackupSnapshot;
+  closure: ICorestoreDatabaseBackupClosureReceipt;
+}
+
+export interface ICorestoreDatabaseBackupRestoreRequest {
+  schemaVersion: 1;
+  targetServiceId: string;
+  receipt: ICorestoreDatabaseBackupReceipt;
+  expectedDatabaseAllocation?: ICorestoreDatabaseAllocationReference;
+  /** Caller-owned idempotency identity. A new value forces a new fenced restore attempt. */
+  restoreAttemptId?: string;
+}
+
+export interface ICorestoreDatabaseBackupRestoreResponse {
+  schemaVersion: 1;
+  ok: true;
+  backupId: string;
+  sourceServiceId: string;
+  targetServiceId: string;
+  snapshotId: string;
+  restoreId: string;
+  requestSha256: string;
+  replayed: boolean;
+}
+
+const corestoreDatabaseBackupIdentifierPattern =
+  /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/;
+const corestoreDatabaseAllocationRehearsalIdPattern =
+  /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,191}$/;
+
+const failCorestoreDatabaseBackup = (reasonArg: string): never => {
+  throw new Error(reasonArg);
+};
+
+const readCorestoreDatabaseBackupRecord = (
+  valueArg: unknown,
+  pathArg: string,
+): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    return failCorestoreDatabaseBackup(`${pathArg} must be a plain object`);
+  }
+  const prototype = Object.getPrototypeOf(valueArg);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return failCorestoreDatabaseBackup(`${pathArg} must be a plain object`);
+  }
+  const value = valueArg as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== 'string') {
+      return failCorestoreDatabaseBackup(`${pathArg} must contain string keys only`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
+      return failCorestoreDatabaseBackup(`${pathArg} must contain data properties only`);
+    }
+  }
+  return value;
+};
+
+const assertCorestoreDatabaseBackupExactKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+  pathArg: string,
+): void => {
+  if (!hasExactKeys(valueArg, keysArg)) {
+    failCorestoreDatabaseBackup(`${pathArg} must use its exact schema`);
+  }
+};
+
+const readCorestoreDatabaseBackupIdentifier = (
+  valueArg: unknown,
+  pathArg: string,
+): string => {
+  if (typeof valueArg !== 'string' || !corestoreDatabaseBackupIdentifierPattern.test(valueArg)) {
+    return failCorestoreDatabaseBackup(`${pathArg} must be a canonical identifier`);
+  }
+  return valueArg;
+};
+
+const readCorestoreDatabaseBackupSha256 = (
+  valueArg: unknown,
+  pathArg: string,
+): string => {
+  if (typeof valueArg !== 'string' || !bareSha256Pattern.test(valueArg)) {
+    return failCorestoreDatabaseBackup(`${pathArg} must be bare lowercase SHA-256`);
+  }
+  return valueArg;
+};
+
+const readCorestoreDatabaseBackupInteger = (
+  valueArg: unknown,
+  pathArg: string,
+  minimumArg: number,
+  maximumArg = Number.MAX_SAFE_INTEGER,
+): number => {
+  if (!Number.isSafeInteger(valueArg)
+    || Object.is(valueArg, -0)
+    || (valueArg as number) < minimumArg
+    || (valueArg as number) > maximumArg) {
+    return failCorestoreDatabaseBackup(`${pathArg} must be a bounded safe integer`);
+  }
+  return valueArg as number;
+};
+
+const finalizeCorestoreDatabaseBackup = <T>(
+  valueArg: T,
+  pathArg: string,
+): Readonly<T> => {
+  const canonical = canonicalizeStrictJson(valueArg, failCorestoreDatabaseBackup, pathArg);
+  if (utf8ByteLength(canonical) > corestoreDatabaseBackupRuntimeLimits.maximumControlBytes) {
+    failCorestoreDatabaseBackup(`${pathArg} exceeds its canonical byte limit`);
+  }
+  return deepFreezeValue(valueArg);
+};
+
+const normalizeCorestoreDatabaseAllocationReferenceInternal = (
+  valueArg: unknown,
+  pathArg: string,
+): ICorestoreDatabaseAllocationReference => {
+  const value = readCorestoreDatabaseBackupRecord(valueArg, pathArg);
+  assertCorestoreDatabaseBackupExactKeys(value, [
+    'purpose',
+    'rehearsalId',
+    'allocationId',
+    'generation',
+    'bindingSha256',
+    'receiptSha256',
+  ], pathArg);
+  if (value.purpose !== 'scratch-rehearsal'
+    || typeof value.rehearsalId !== 'string'
+    || !corestoreDatabaseAllocationRehearsalIdPattern.test(value.rehearsalId)) {
+    failCorestoreDatabaseBackup(`${pathArg} rehearsal authority must be canonical`);
+  }
+  const rehearsalId = value.rehearsalId as string;
+  return {
+    purpose: 'scratch-rehearsal',
+    rehearsalId,
+    allocationId: readCorestoreDatabaseBackupSha256(
+      value.allocationId,
+      `${pathArg}.allocationId`,
+    ),
+    generation: readCorestoreDatabaseBackupInteger(
+      value.generation,
+      `${pathArg}.generation`,
+      1,
+    ),
+    bindingSha256: readCorestoreDatabaseBackupSha256(
+      value.bindingSha256,
+      `${pathArg}.bindingSha256`,
+    ),
+    receiptSha256: readCorestoreDatabaseBackupSha256(
+      value.receiptSha256,
+      `${pathArg}.receiptSha256`,
+    ),
+  };
+};
+
+export const normalizeCorestoreDatabaseAllocationReference = (
+  valueArg: unknown,
+): Readonly<ICorestoreDatabaseAllocationReference> => finalizeCorestoreDatabaseBackup(
+  normalizeCorestoreDatabaseAllocationReferenceInternal(valueArg, 'databaseAllocation'),
+  'databaseAllocation',
+);
+
+const normalizeCorestoreDatabaseBackupReceiptInternal = (
+  valueArg: unknown,
+  pathArg: string,
+): ICorestoreDatabaseBackupReceipt => {
+  const value = readCorestoreDatabaseBackupRecord(valueArg, pathArg);
+  assertCorestoreDatabaseBackupExactKeys(value, [
+    'schemaVersion',
+    'format',
+    'backupId',
+    'sourceServiceId',
+    'createdAt',
+    'snapshot',
+    'closure',
+  ], pathArg);
+  if (value.schemaVersion !== 1 || value.format !== 'corestore.database.backup.v1') {
+    failCorestoreDatabaseBackup(`${pathArg} version must be canonical`);
+  }
+  const backupId = readCorestoreDatabaseBackupIdentifier(value.backupId, `${pathArg}.backupId`);
+  const sourceServiceId = readCorestoreDatabaseBackupIdentifier(
+    value.sourceServiceId,
+    `${pathArg}.sourceServiceId`,
+  );
+  const createdAt = readCorestoreDatabaseBackupInteger(value.createdAt, `${pathArg}.createdAt`, 1);
+  const snapshotValue = readCorestoreDatabaseBackupRecord(value.snapshot, `${pathArg}.snapshot`);
+  const hasDatabaseAllocation = Object.hasOwn(snapshotValue, 'databaseAllocation');
+  assertCorestoreDatabaseBackupExactKeys(snapshotValue, [
+    'capability',
+    'resourceName',
+    'snapshotId',
+    'snapshotName',
+    'originalSize',
+    'storedSize',
+    'createdAt',
+    'tags',
+    'databaseName',
+    ...(hasDatabaseAllocation ? ['databaseAllocation'] : []),
+  ], `${pathArg}.snapshot`);
+  if (snapshotValue.capability !== 'database') {
+    failCorestoreDatabaseBackup(`${pathArg}.snapshot capability must be database`);
+  }
+  const resourceName = readCorestoreDatabaseBackupIdentifier(
+    snapshotValue.resourceName,
+    `${pathArg}.snapshot.resourceName`,
+  );
+  const snapshotId = readCorestoreDatabaseBackupIdentifier(
+    snapshotValue.snapshotId,
+    `${pathArg}.snapshot.snapshotId`,
+  );
+  const snapshotName = readCorestoreDatabaseBackupIdentifier(
+    snapshotValue.snapshotName,
+    `${pathArg}.snapshot.snapshotName`,
+  );
+  const databaseName = readCorestoreDatabaseBackupIdentifier(
+    snapshotValue.databaseName,
+    `${pathArg}.snapshot.databaseName`,
+  );
+  const snapshotCreatedAt = readCorestoreDatabaseBackupInteger(
+    snapshotValue.createdAt,
+    `${pathArg}.snapshot.createdAt`,
+    1,
+  );
+  if (snapshotName !== backupId || snapshotCreatedAt !== createdAt) {
+    failCorestoreDatabaseBackup(`${pathArg}.snapshot identity must match its receipt`);
+  }
+  const tagsValue = readCorestoreDatabaseBackupRecord(
+    snapshotValue.tags,
+    `${pathArg}.snapshot.tags`,
+  );
+  assertCorestoreDatabaseBackupExactKeys(tagsValue, [
+    'corestore',
+    'serviceId',
+    'serviceName',
+    'capability',
+    'resourceName',
+    'snapshotName',
+    'backupId',
+  ], `${pathArg}.snapshot.tags`);
+  if (tagsValue.corestore !== 'resource'
+    || tagsValue.serviceId !== sourceServiceId
+    || tagsValue.capability !== 'database'
+    || tagsValue.resourceName !== resourceName
+    || tagsValue.snapshotName !== backupId
+    || tagsValue.backupId !== backupId
+    || typeof tagsValue.serviceName !== 'string'
+    || tagsValue.serviceName.length > 256
+    || utf8ByteLength(tagsValue.serviceName)
+      > corestoreDatabaseBackupRuntimeLimits.maximumServiceNameBytes) {
+    failCorestoreDatabaseBackup(`${pathArg}.snapshot.tags ownership must be canonical`);
+  }
+  const serviceName = tagsValue.serviceName as string;
+  const closureValue = readCorestoreDatabaseBackupRecord(value.closure, `${pathArg}.closure`);
+  assertCorestoreDatabaseBackupExactKeys(closureValue, [
+    'formatVersion',
+    'snapshotIds',
+    'objectCount',
+    'packCount',
+    'chunkCount',
+    'payloadBytes',
+    'archiveBytes',
+    'sha256',
+  ], `${pathArg}.closure`);
+  if (!Array.isArray(closureValue.snapshotIds)
+    || Object.getPrototypeOf(closureValue.snapshotIds) !== Array.prototype
+    || closureValue.snapshotIds.length !== 1
+    || !Object.hasOwn(closureValue.snapshotIds, 0)
+    || Reflect.ownKeys(closureValue.snapshotIds).some((keyArg) => keyArg !== 'length' && keyArg !== '0')) {
+    failCorestoreDatabaseBackup(`${pathArg}.closure snapshot coverage must be exact`);
+  }
+  const snapshotIdDescriptor = Object.getOwnPropertyDescriptor(closureValue.snapshotIds, '0');
+  if (!snapshotIdDescriptor
+    || !snapshotIdDescriptor.enumerable
+    || !Object.hasOwn(snapshotIdDescriptor, 'value')
+    || snapshotIdDescriptor.value !== snapshotId) {
+    failCorestoreDatabaseBackup(`${pathArg}.closure snapshot coverage must use data entries`);
+  }
+  const objectCount = readCorestoreDatabaseBackupInteger(
+    closureValue.objectCount,
+    `${pathArg}.closure.objectCount`,
+    1,
+    corestoreDatabaseBackupRuntimeLimits.maximumClosureObjects,
+  );
+  const packCount = readCorestoreDatabaseBackupInteger(
+    closureValue.packCount,
+    `${pathArg}.closure.packCount`,
+    1,
+    corestoreDatabaseBackupRuntimeLimits.maximumClosureObjects,
+  );
+  const chunkCount = readCorestoreDatabaseBackupInteger(
+    closureValue.chunkCount,
+    `${pathArg}.closure.chunkCount`,
+    1,
+    corestoreDatabaseBackupRuntimeLimits.maximumClosureChunks,
+  );
+  if (packCount > objectCount) {
+    failCorestoreDatabaseBackup(`${pathArg}.closure pack coverage must be canonical`);
+  }
+  const originalSize = readCorestoreDatabaseBackupInteger(
+    snapshotValue.originalSize,
+    `${pathArg}.snapshot.originalSize`,
+    1,
+    corestoreDatabaseBackupRuntimeLimits.maximumSnapshotOriginalBytes,
+  );
+  const storedSize = readCorestoreDatabaseBackupInteger(
+    snapshotValue.storedSize,
+    `${pathArg}.snapshot.storedSize`,
+    1,
+    corestoreDatabaseBackupRuntimeLimits.maximumClosureBytes,
+  );
+  const databaseAllocation = hasDatabaseAllocation
+    ? normalizeCorestoreDatabaseAllocationReferenceInternal(
+        snapshotValue.databaseAllocation,
+        `${pathArg}.snapshot.databaseAllocation`,
+      )
+    : undefined;
+  return {
+    schemaVersion: 1,
+    format: 'corestore.database.backup.v1',
+    backupId,
+    sourceServiceId,
+    createdAt,
+    snapshot: {
+      capability: 'database',
+      resourceName,
+      snapshotId,
+      snapshotName,
+      originalSize,
+      storedSize,
+      createdAt: snapshotCreatedAt,
+      tags: {
+        corestore: 'resource',
+        serviceId: sourceServiceId,
+        serviceName,
+        capability: 'database',
+        resourceName,
+        snapshotName,
+        backupId,
+      },
+      databaseName,
+      ...(databaseAllocation ? { databaseAllocation } : {}),
+    },
+    closure: {
+      formatVersion: closureValue.formatVersion === 1
+        ? 1
+        : failCorestoreDatabaseBackup(`${pathArg}.closure formatVersion must be 1`),
+      snapshotIds: [snapshotId],
+      objectCount,
+      packCount,
+      chunkCount,
+      payloadBytes: readCorestoreDatabaseBackupInteger(
+        closureValue.payloadBytes,
+        `${pathArg}.closure.payloadBytes`,
+        1,
+        corestoreDatabaseBackupRuntimeLimits.maximumClosureBytes,
+      ),
+      archiveBytes: readCorestoreDatabaseBackupInteger(
+        closureValue.archiveBytes,
+        `${pathArg}.closure.archiveBytes`,
+        1,
+        corestoreDatabaseBackupRuntimeLimits.maximumClosureBytes,
+      ),
+      sha256: readCorestoreDatabaseBackupSha256(
+        closureValue.sha256,
+        `${pathArg}.closure.sha256`,
+      ),
+    },
+  };
+};
+
+export const normalizeCorestoreDatabaseBackupReceipt = (
+  valueArg: unknown,
+): Readonly<ICorestoreDatabaseBackupReceipt> => finalizeCorestoreDatabaseBackup(
+  normalizeCorestoreDatabaseBackupReceiptInternal(valueArg, 'databaseBackupReceipt'),
+  'databaseBackupReceipt',
+);
+
+export const normalizeCorestoreDatabaseBackupRestoreRequest = (
+  valueArg: unknown,
+): Readonly<ICorestoreDatabaseBackupRestoreRequest> => {
+  const value = readCorestoreDatabaseBackupRecord(valueArg, 'databaseBackupRestoreRequest');
+  const hasAllocation = Object.hasOwn(value, 'expectedDatabaseAllocation');
+  const hasRestoreAttemptId = Object.hasOwn(value, 'restoreAttemptId');
+  assertCorestoreDatabaseBackupExactKeys(value, [
+    'schemaVersion',
+    'targetServiceId',
+    'receipt',
+    ...(hasAllocation ? ['expectedDatabaseAllocation'] : []),
+    ...(hasRestoreAttemptId ? ['restoreAttemptId'] : []),
+  ], 'databaseBackupRestoreRequest');
+  if (value.schemaVersion !== 1) {
+    failCorestoreDatabaseBackup('databaseBackupRestoreRequest schemaVersion must be 1');
+  }
+  const receipt = normalizeCorestoreDatabaseBackupReceiptInternal(
+    value.receipt,
+    'databaseBackupRestoreRequest.receipt',
+  );
+  const expectedDatabaseAllocation = hasAllocation
+    ? normalizeCorestoreDatabaseAllocationReferenceInternal(
+        value.expectedDatabaseAllocation,
+        'databaseBackupRestoreRequest.expectedDatabaseAllocation',
+      )
+    : undefined;
+  const restoreAttemptId = hasRestoreAttemptId
+    ? readCorestoreDatabaseBackupIdentifier(
+        value.restoreAttemptId,
+        'databaseBackupRestoreRequest.restoreAttemptId',
+      )
+    : undefined;
+  return finalizeCorestoreDatabaseBackup({
+    schemaVersion: 1,
+    targetServiceId: readCorestoreDatabaseBackupIdentifier(
+      value.targetServiceId,
+      'databaseBackupRestoreRequest.targetServiceId',
+    ),
+    receipt,
+    ...(expectedDatabaseAllocation ? { expectedDatabaseAllocation } : {}),
+    ...(restoreAttemptId ? { restoreAttemptId } : {}),
+  }, 'databaseBackupRestoreRequest');
+};
+
+export const normalizeCorestoreDatabaseBackupRestoreResponse = (
+  valueArg: unknown,
+): Readonly<ICorestoreDatabaseBackupRestoreResponse> => {
+  const value = readCorestoreDatabaseBackupRecord(valueArg, 'databaseBackupRestoreResponse');
+  assertCorestoreDatabaseBackupExactKeys(value, [
+    'schemaVersion',
+    'ok',
+    'backupId',
+    'sourceServiceId',
+    'targetServiceId',
+    'snapshotId',
+    'restoreId',
+    'requestSha256',
+    'replayed',
+  ], 'databaseBackupRestoreResponse');
+  if (value.schemaVersion !== 1 || value.ok !== true || typeof value.replayed !== 'boolean') {
+    failCorestoreDatabaseBackup('databaseBackupRestoreResponse constants must be canonical');
+  }
+  const replayed = value.replayed as boolean;
+  return finalizeCorestoreDatabaseBackup({
+    schemaVersion: 1,
+    ok: true,
+    backupId: readCorestoreDatabaseBackupIdentifier(
+      value.backupId,
+      'databaseBackupRestoreResponse.backupId',
+    ),
+    sourceServiceId: readCorestoreDatabaseBackupIdentifier(
+      value.sourceServiceId,
+      'databaseBackupRestoreResponse.sourceServiceId',
+    ),
+    targetServiceId: readCorestoreDatabaseBackupIdentifier(
+      value.targetServiceId,
+      'databaseBackupRestoreResponse.targetServiceId',
+    ),
+    snapshotId: readCorestoreDatabaseBackupIdentifier(
+      value.snapshotId,
+      'databaseBackupRestoreResponse.snapshotId',
+    ),
+    restoreId: readCorestoreDatabaseBackupIdentifier(
+      value.restoreId,
+      'databaseBackupRestoreResponse.restoreId',
+    ),
+    requestSha256: readCorestoreDatabaseBackupSha256(
+      value.requestSha256,
+      'databaseBackupRestoreResponse.requestSha256',
+    ),
+    replayed,
+  }, 'databaseBackupRestoreResponse');
+};
+
+const createCorestoreDatabaseBackupCanonicalJson = (
+  valueArg: unknown,
+  pathArg: string,
+): string => canonicalizeStrictJson(valueArg, failCorestoreDatabaseBackup, pathArg);
+
+export const encodeCorestoreDatabaseAllocationReference = (
+  valueArg: unknown,
+): Uint8Array => new TextEncoder().encode(createCorestoreDatabaseBackupCanonicalJson(
+  normalizeCorestoreDatabaseAllocationReference(valueArg),
+  'databaseAllocation',
+));
+
+export const encodeCorestoreDatabaseBackupReceipt = (
+  valueArg: unknown,
+): Uint8Array => new TextEncoder().encode(createCorestoreDatabaseBackupCanonicalJson(
+  normalizeCorestoreDatabaseBackupReceipt(valueArg),
+  'databaseBackupReceipt',
+));
+
+export const encodeCorestoreDatabaseBackupRestoreRequest = (
+  valueArg: unknown,
+): Uint8Array => new TextEncoder().encode(createCorestoreDatabaseBackupCanonicalJson(
+  normalizeCorestoreDatabaseBackupRestoreRequest(valueArg),
+  'databaseBackupRestoreRequest',
+));
+
+export const encodeCorestoreDatabaseBackupRestoreResponse = (
+  valueArg: unknown,
+): Uint8Array => new TextEncoder().encode(createCorestoreDatabaseBackupCanonicalJson(
+  normalizeCorestoreDatabaseBackupRestoreResponse(valueArg),
+  'databaseBackupRestoreResponse',
+));
+
+export const computeCorestoreDatabaseAllocationReferenceSha256 = async (
+  valueArg: unknown,
+): Promise<string> => createCanonicalJsonSha256Hex(
+  createCorestoreDatabaseBackupCanonicalJson(
+    normalizeCorestoreDatabaseAllocationReference(valueArg),
+    'databaseAllocation',
+  ),
+  failCorestoreDatabaseBackup,
+);
+
+export const computeCorestoreDatabaseBackupReceiptSha256 = async (
+  valueArg: unknown,
+): Promise<string> => createCanonicalJsonSha256Hex(
+  createCorestoreDatabaseBackupCanonicalJson(
+    normalizeCorestoreDatabaseBackupReceipt(valueArg),
+    'databaseBackupReceipt',
+  ),
+  failCorestoreDatabaseBackup,
+);
+
+export const computeCorestoreDatabaseBackupRestoreRequestSha256 = async (
+  valueArg: unknown,
+): Promise<string> => createCanonicalJsonSha256Hex(
+  createCorestoreDatabaseBackupCanonicalJson(
+    normalizeCorestoreDatabaseBackupRestoreRequest(valueArg),
+    'databaseBackupRestoreRequest',
+  ),
+  failCorestoreDatabaseBackup,
+);
+
+export const computeCorestoreDatabaseBackupRestoreResponseSha256 = async (
+  valueArg: unknown,
+): Promise<string> => createCanonicalJsonSha256Hex(
+  createCorestoreDatabaseBackupCanonicalJson(
+    normalizeCorestoreDatabaseBackupRestoreResponse(valueArg),
+    'databaseBackupRestoreResponse',
+  ),
+  failCorestoreDatabaseBackup,
+);