@serve.zone/interfaces 32.1.0 → 32.2.0

package/ts/private/storagecontract.ts

@@ -0,0 +1,623 @@
+/**
+ * The readers a storage control body is judged by, and the one normalizer that turns a storage
+ * request into the exact value its digest is taken over.
+ *
+ * Two modules judge the same bytes in their own error vocabulary — `platform/storage.ts` for a
+ * storage request on its own and `platform/storagemigration.ts` for the migration control plane
+ * that carries one — so the rules take the failure they report through. A second copy of them
+ * would be a second answer to what a request is, and a request digest that a control plane issues
+ * and a consumer re-derives would stop being one value.
+ */
+import type {
+  IAppStoreFilesystemStorageRequest,
+  IAppStoreObjectStorageRequest,
+  TAppStoreStorageRequest,
+} from '../appstore/types.js';
+import { normalizeServiceAbsolutePath } from '../data/service.js';
+import type { TObjectStorageDelivery } from '../platform/storage.js';
+import type { TCanonicalJsonFailure } from './canonicaljson.js';
+
+/** Byte bounds every reader of a storage control string applies. */
+export const storageContractStringLimits = Object.freeze({
+  maximumConfiguredStringBytes: 2048,
+  maximumEnvironmentKeyBytes: 256,
+  maximumSecretPathBytes: 2048,
+});
+
+const canonicalIdPattern = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,191}$/;
+const environmentKeyPattern = /^[A-Z_][A-Z0-9_]{0,255}$/;
+const sha256Pattern = /^[a-f0-9]{64}$/;
+const capacityPattern = /^[1-9][0-9]*(?:KiB|MiB|GiB|TiB)$/;
+/**
+ * The mount a Secret file is delivered under. A filesystem request that mounts it, or anything
+ * containing it, would shadow every credential the platform writes for the same service.
+ */
+const secretDeliveryRoot = '/run/secrets';
+
+export const createStorageContractReaders = (failArg: TCanonicalJsonFailure) => {
+  const utf8ByteLength = (valueArg: string): number => {
+    return new TextEncoder().encode(valueArg).byteLength;
+  };
+
+  const readRecord = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): Record<string, unknown> => {
+    if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+      return failArg(`${fieldNameArg} must be a plain object`);
+    }
+    const prototype = Object.getPrototypeOf(valueArg);
+    if (prototype !== Object.prototype && prototype !== null) {
+      return failArg(`${fieldNameArg} must be a plain object`);
+    }
+    const record = valueArg as Record<string, unknown>;
+    const ownKeys = Reflect.ownKeys(record);
+    if (ownKeys.some((keyArg) => typeof keyArg !== 'string')) {
+      return failArg(`${fieldNameArg} must not contain symbol keys`);
+    }
+    for (const key of ownKeys as string[]) {
+      const descriptor = Object.getOwnPropertyDescriptor(record, key);
+      if (
+        !descriptor ||
+        !descriptor.enumerable ||
+        !Object.hasOwn(descriptor, 'value') ||
+        descriptor.value === undefined
+      ) {
+        return failArg(
+          `${fieldNameArg} must contain enumerable JSON data properties only`,
+        );
+      }
+    }
+    return record;
+  };
+
+  const readDenseArray = (
+    valueArg: unknown,
+    fieldNameArg: string,
+    minimumLengthArg: number,
+    maximumLengthArg: number,
+  ): unknown[] => {
+    if (
+      !Array.isArray(valueArg) ||
+      Object.getPrototypeOf(valueArg) !== Array.prototype
+    ) {
+      return failArg(`${fieldNameArg} must be a dense plain array`);
+    }
+    if (
+      valueArg.length < minimumLengthArg ||
+      valueArg.length > maximumLengthArg
+    ) {
+      return failArg(
+        `${fieldNameArg} must contain between ${minimumLengthArg} and ${maximumLengthArg} entries`,
+      );
+    }
+    for (let index = 0; index < valueArg.length; index++) {
+      if (!Object.hasOwn(valueArg, index)) {
+        return failArg(`${fieldNameArg} must not contain sparse entries`);
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(valueArg, String(index));
+      if (
+        !descriptor ||
+        !descriptor.enumerable ||
+        !Object.hasOwn(descriptor, 'value') ||
+        descriptor.value === undefined
+      ) {
+        return failArg(
+          `${fieldNameArg} must contain enumerable JSON data entries only`,
+        );
+      }
+    }
+    for (const key of Reflect.ownKeys(valueArg)) {
+      if (key === 'length') continue;
+      if (
+        typeof key !== 'string' ||
+        !/^(?:0|[1-9][0-9]*)$/.test(key) ||
+        Number(key) >= valueArg.length
+      ) {
+        return failArg(`${fieldNameArg} must not contain extra properties`);
+      }
+    }
+    return valueArg;
+  };
+
+  const assertKeys = (
+    recordArg: Record<string, unknown>,
+    requiredKeysArg: readonly string[],
+    optionalKeysArg: readonly string[],
+    fieldNameArg: string,
+  ): void => {
+    const actualKeys = Object.keys(recordArg).sort();
+    const allowedKeys = new Set([...requiredKeysArg, ...optionalKeysArg]);
+    if (
+      requiredKeysArg.some((keyArg) => !Object.hasOwn(recordArg, keyArg)) ||
+      actualKeys.some((keyArg) => !allowedKeys.has(keyArg))
+    ) {
+      failArg(`${fieldNameArg} does not match its exact schema`);
+    }
+  };
+
+  const assertExactKeys = (
+    recordArg: Record<string, unknown>,
+    expectedKeysArg: readonly string[],
+    fieldNameArg: string,
+  ): void => {
+    assertKeys(recordArg, expectedKeysArg, [], fieldNameArg);
+  };
+
+  const readString = (
+    valueArg: unknown,
+    fieldNameArg: string,
+    maximumBytesArg: number =
+      storageContractStringLimits.maximumConfiguredStringBytes,
+  ): string => {
+    if (
+      typeof valueArg !== 'string' ||
+      valueArg.length === 0 ||
+      utf8ByteLength(valueArg) > maximumBytesArg ||
+      /[\u0000-\u001f\u007f]/u.test(valueArg)
+    ) {
+      return failArg(`${fieldNameArg} must be a bounded non-empty JSON string`);
+    }
+    for (let index = 0; index < valueArg.length; index++) {
+      const codeUnit = valueArg.charCodeAt(index);
+      if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+        const following = valueArg.charCodeAt(index + 1);
+        if (following < 0xdc00 || following > 0xdfff) {
+          return failArg(`${fieldNameArg} contains an unpaired UTF-16 surrogate`);
+        }
+        index++;
+      } else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+        return failArg(`${fieldNameArg} contains an unpaired UTF-16 surrogate`);
+      }
+    }
+    return valueArg;
+  };
+
+  const readIdentifier = (valueArg: unknown, fieldNameArg: string): string => {
+    if (typeof valueArg !== 'string' || !canonicalIdPattern.test(valueArg)) {
+      return failArg(`${fieldNameArg} must be a canonical identifier`);
+    }
+    return valueArg;
+  };
+
+  const readSha256 = (valueArg: unknown, fieldNameArg: string): string => {
+    if (typeof valueArg !== 'string' || !sha256Pattern.test(valueArg)) {
+      return failArg(`${fieldNameArg} must be a bare lowercase 64-hex SHA-256 digest`);
+    }
+    return valueArg;
+  };
+
+  const readSafeInteger = (
+    valueArg: unknown,
+    fieldNameArg: string,
+    minimumArg: number,
+    maximumArg = Number.MAX_SAFE_INTEGER,
+  ): number => {
+    if (
+      typeof valueArg !== 'number' ||
+      !Number.isSafeInteger(valueArg) ||
+      Object.is(valueArg, -0) ||
+      valueArg < minimumArg ||
+      valueArg > maximumArg
+    ) {
+      return failArg(
+        `${fieldNameArg} must be a safe integer between ${minimumArg} and ${maximumArg}`,
+      );
+    }
+    return valueArg;
+  };
+
+  const readBoolean = (valueArg: unknown, fieldNameArg: string): boolean => {
+    if (typeof valueArg !== 'boolean') {
+      return failArg(`${fieldNameArg} must be a boolean`);
+    }
+    return valueArg;
+  };
+
+  const readLiteral = <TLiteral extends string>(
+    valueArg: unknown,
+    allowedArg: readonly TLiteral[],
+    fieldNameArg: string,
+  ): TLiteral => {
+    if (
+      typeof valueArg !== 'string' ||
+      !allowedArg.includes(valueArg as TLiteral)
+    ) {
+      return failArg(`${fieldNameArg} is outside the supported values`);
+    }
+    return valueArg as TLiteral;
+  };
+
+  const readCapacityQuantity = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): string => {
+    if (typeof valueArg !== 'string' || !capacityPattern.test(valueArg)) {
+      return failArg(`${fieldNameArg} must be a canonical base-2 capacity quantity`);
+    }
+    const numericPart = valueArg.replace(/(?:KiB|MiB|GiB|TiB)$/, '');
+    if (!Number.isSafeInteger(Number(numericPart))) {
+      return failArg(`${fieldNameArg} exceeds the safe integer quantity range`);
+    }
+    return valueArg;
+  };
+
+  const capacityQuantityBytes = (valueArg: string): bigint => {
+    const units: Record<string, bigint> = {
+      KiB: 1024n,
+      MiB: 1024n ** 2n,
+      GiB: 1024n ** 3n,
+      TiB: 1024n ** 4n,
+    };
+    const unit = valueArg.slice(-3);
+    return BigInt(valueArg.slice(0, -3)) * units[unit];
+  };
+
+  const normalizeCapacityRequest = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): NonNullable<TAppStoreStorageRequest['capacity']> => {
+    const value = readRecord(valueArg, fieldNameArg);
+    assertKeys(value, ['request'], ['limit'], fieldNameArg);
+    const request = readCapacityQuantity(value.request, `${fieldNameArg}.request`);
+    const limit = Object.hasOwn(value, 'limit')
+      ? readCapacityQuantity(value.limit, `${fieldNameArg}.limit`)
+      : undefined;
+    if (limit && capacityQuantityBytes(limit) < capacityQuantityBytes(request)) {
+      return failArg(`${fieldNameArg}.limit must be at least request`);
+    }
+    return {
+      request,
+      ...(limit ? { limit } : {}),
+    };
+  };
+
+  const readEnvironmentKey = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): string => {
+    if (
+      typeof valueArg !== 'string' ||
+      utf8ByteLength(valueArg) >
+        storageContractStringLimits.maximumEnvironmentKeyBytes ||
+      !environmentKeyPattern.test(valueArg)
+    ) {
+      return failArg(`${fieldNameArg} must be a canonical environment key`);
+    }
+    return valueArg;
+  };
+
+  const normalizeDelivery = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): TObjectStorageDelivery => {
+    const value = readRecord(valueArg, fieldNameArg);
+    if (value.type === 'launcher-environment') {
+      assertExactKeys(value, ['type', 'keys'], fieldNameArg);
+      const keys = readRecord(value.keys, `${fieldNameArg}.keys`);
+      assertKeys(
+        keys,
+        ['endpoint', 'bucket', 'region', 'accessKeyId', 'secretAccessKey'],
+        ['sessionToken'],
+        `${fieldNameArg}.keys`,
+      );
+      const normalizedKeys = {
+        endpoint: readEnvironmentKey(
+          keys.endpoint,
+          `${fieldNameArg}.keys.endpoint`,
+        ),
+        bucket: readEnvironmentKey(keys.bucket, `${fieldNameArg}.keys.bucket`),
+        region: readEnvironmentKey(keys.region, `${fieldNameArg}.keys.region`),
+        accessKeyId: readEnvironmentKey(
+          keys.accessKeyId,
+          `${fieldNameArg}.keys.accessKeyId`,
+        ),
+        secretAccessKey: readEnvironmentKey(
+          keys.secretAccessKey,
+          `${fieldNameArg}.keys.secretAccessKey`,
+        ),
+        ...(Object.hasOwn(keys, 'sessionToken')
+          ? {
+              sessionToken: readEnvironmentKey(
+                keys.sessionToken,
+                `${fieldNameArg}.keys.sessionToken`,
+              ),
+            }
+          : {}),
+      };
+      if (
+        new Set(Object.values(normalizedKeys)).size !==
+        Object.keys(normalizedKeys).length
+      ) {
+        return failArg(`${fieldNameArg}.keys values must be distinct`);
+      }
+      return { type: 'launcher-environment', keys: normalizedKeys };
+    }
+    if (value.type === 'file') {
+      assertExactKeys(value, ['type', 'targetPath', 'format', 'uid', 'gid', 'mode'], fieldNameArg);
+      const targetPath = readString(
+        value.targetPath,
+        `${fieldNameArg}.targetPath`,
+        storageContractStringLimits.maximumSecretPathBytes,
+      );
+      if (
+        !targetPath.startsWith(`${secretDeliveryRoot}/`) ||
+        targetPath.includes('\\') ||
+        targetPath.split('/').some((segmentArg) =>
+          segmentArg === '.' || segmentArg === '..'
+        )
+      ) {
+        return failArg(
+          `${fieldNameArg}.targetPath must be a canonical path below ${secretDeliveryRoot}`,
+        );
+      }
+      if (value.format !== 'servezone-object-storage') {
+        return failArg(`${fieldNameArg}.format is unsupported`);
+      }
+      return {
+        type: 'file',
+        targetPath,
+        format: 'servezone-object-storage',
+        uid: readSafeInteger(value.uid, `${fieldNameArg}.uid`, 0, 2_147_483_647),
+        gid: readSafeInteger(value.gid, `${fieldNameArg}.gid`, 0, 2_147_483_647),
+        mode: value.mode === 0o400 || value.mode === 0o440
+          ? value.mode
+          : failArg(`${fieldNameArg}.mode must be 0400 or 0440`),
+      };
+    }
+    return failArg(`${fieldNameArg}.type is unsupported`);
+  };
+
+  const normalizeObjectStorageProtection = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): NonNullable<IAppStoreObjectStorageRequest['protection']> => {
+    const value = readRecord(valueArg, fieldNameArg);
+    assertKeys(
+      value,
+      [],
+      ['backup', 'versioning', 'retentionDays'],
+      fieldNameArg,
+    );
+    if (Object.keys(value).length === 0) {
+      return failArg(`${fieldNameArg} must not be empty`);
+    }
+    return {
+      ...(Object.hasOwn(value, 'backup')
+        ? {
+            backup: value.backup === 'required'
+              ? 'required' as const
+              : failArg(`${fieldNameArg}.backup must be required`),
+          }
+        : {}),
+      ...(Object.hasOwn(value, 'versioning')
+        ? {
+            versioning: value.versioning === 'required'
+              ? 'required' as const
+              : failArg(`${fieldNameArg}.versioning must be required`),
+          }
+        : {}),
+      ...(Object.hasOwn(value, 'retentionDays')
+        ? {
+            retentionDays: readSafeInteger(
+              value.retentionDays,
+              `${fieldNameArg}.retentionDays`,
+              1,
+              365_000,
+            ),
+          }
+        : {}),
+    };
+  };
+
+  const normalizeFilesystemProtection = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): NonNullable<IAppStoreFilesystemStorageRequest['protection']> => {
+    const value = readRecord(valueArg, fieldNameArg);
+    assertKeys(value, [], ['backup', 'snapshots', 'consistency'], fieldNameArg);
+    if (Object.keys(value).length === 0) {
+      return failArg(`${fieldNameArg} must not be empty`);
+    }
+    return {
+      ...(Object.hasOwn(value, 'backup')
+        ? {
+            backup: value.backup === 'required'
+              ? 'required' as const
+              : failArg(`${fieldNameArg}.backup must be required`),
+          }
+        : {}),
+      ...(Object.hasOwn(value, 'snapshots')
+        ? {
+            snapshots: readLiteral(
+              value.snapshots,
+              ['portable', 'native'] as const,
+              `${fieldNameArg}.snapshots`,
+            ),
+          }
+        : {}),
+      ...(Object.hasOwn(value, 'consistency')
+        ? {
+            consistency: readLiteral(
+              value.consistency,
+              ['crashConsistent', 'applicationConsistent'] as const,
+              `${fieldNameArg}.consistency`,
+            ),
+          }
+        : {}),
+    };
+  };
+
+  const readMountPath = (valueArg: unknown, fieldNameArg: string): string => {
+    const value = readString(
+      valueArg,
+      fieldNameArg,
+      storageContractStringLimits.maximumSecretPathBytes,
+    );
+    if (normalizeServiceAbsolutePath(value) !== value || value === '/') {
+      return failArg(
+        `${fieldNameArg} must be a canonical non-root absolute path`,
+      );
+    }
+    if (
+      value === secretDeliveryRoot ||
+      value.startsWith(`${secretDeliveryRoot}/`) ||
+      secretDeliveryRoot.startsWith(`${value}/`)
+    ) {
+      return failArg(`${fieldNameArg} must not overlap ${secretDeliveryRoot}`);
+    }
+    return value;
+  };
+
+  const normalizeObjectStorageRequest = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): IAppStoreObjectStorageRequest => {
+    const value = readRecord(valueArg, fieldNameArg);
+    assertKeys(
+      value,
+      [
+        'id',
+        'kind',
+        'storageClass',
+        'accessMode',
+        'reclaimPolicy',
+        'delivery',
+      ],
+      ['capacity', 'protection'],
+      fieldNameArg,
+    );
+    if (value.kind !== 'objectStorage') {
+      return failArg(`${fieldNameArg}.kind must be objectStorage`);
+    }
+    return {
+      id: readIdentifier(value.id, `${fieldNameArg}.id`),
+      kind: 'objectStorage',
+      storageClass: readIdentifier(
+        value.storageClass,
+        `${fieldNameArg}.storageClass`,
+      ),
+      accessMode: readLiteral(
+        value.accessMode,
+        ['readOnly', 'readWrite'] as const,
+        `${fieldNameArg}.accessMode`,
+      ),
+      reclaimPolicy: readLiteral(
+        value.reclaimPolicy,
+        ['retain', 'delete'] as const,
+        `${fieldNameArg}.reclaimPolicy`,
+      ),
+      delivery: normalizeDelivery(value.delivery, `${fieldNameArg}.delivery`),
+      ...(Object.hasOwn(value, 'capacity')
+        ? {
+            capacity: normalizeCapacityRequest(
+              value.capacity,
+              `${fieldNameArg}.capacity`,
+            ),
+          }
+        : {}),
+      ...(Object.hasOwn(value, 'protection')
+        ? {
+            protection: normalizeObjectStorageProtection(
+              value.protection,
+              `${fieldNameArg}.protection`,
+            ),
+          }
+        : {}),
+    };
+  };
+
+  const normalizeFilesystemStorageRequest = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): IAppStoreFilesystemStorageRequest => {
+    const value = readRecord(valueArg, fieldNameArg);
+    assertKeys(
+      value,
+      [
+        'id',
+        'kind',
+        'storageClass',
+        'accessMode',
+        'reclaimPolicy',
+        'mountPath',
+      ],
+      ['capacity', 'protection'],
+      fieldNameArg,
+    );
+    if (value.kind !== 'filesystem') {
+      return failArg(`${fieldNameArg}.kind must be filesystem`);
+    }
+    return {
+      id: readIdentifier(value.id, `${fieldNameArg}.id`),
+      kind: 'filesystem',
+      storageClass: readIdentifier(
+        value.storageClass,
+        `${fieldNameArg}.storageClass`,
+      ),
+      accessMode: readLiteral(
+        value.accessMode,
+        ['ReadWriteOnce', 'ReadOnlyMany', 'ReadWriteMany'] as const,
+        `${fieldNameArg}.accessMode`,
+      ),
+      reclaimPolicy: readLiteral(
+        value.reclaimPolicy,
+        ['retain', 'delete'] as const,
+        `${fieldNameArg}.reclaimPolicy`,
+      ),
+      mountPath: readMountPath(value.mountPath, `${fieldNameArg}.mountPath`),
+      ...(Object.hasOwn(value, 'capacity')
+        ? {
+            capacity: normalizeCapacityRequest(
+              value.capacity,
+              `${fieldNameArg}.capacity`,
+            ),
+          }
+        : {}),
+      ...(Object.hasOwn(value, 'protection')
+        ? {
+            protection: normalizeFilesystemProtection(
+              value.protection,
+              `${fieldNameArg}.protection`,
+            ),
+          }
+        : {}),
+    };
+  };
+
+  const normalizeStorageRequest = (
+    valueArg: unknown,
+    fieldNameArg: string,
+  ): TAppStoreStorageRequest => {
+    const value = readRecord(valueArg, fieldNameArg);
+    if (value.kind === 'filesystem') {
+      return normalizeFilesystemStorageRequest(value, fieldNameArg);
+    }
+    if (value.kind === 'objectStorage') {
+      return normalizeObjectStorageRequest(value, fieldNameArg);
+    }
+    return failArg(`${fieldNameArg}.kind must be filesystem or objectStorage`);
+  };
+
+  return {
+    utf8ByteLength,
+    readRecord,
+    readDenseArray,
+    assertKeys,
+    assertExactKeys,
+    readString,
+    readIdentifier,
+    readSha256,
+    readSafeInteger,
+    readBoolean,
+    readLiteral,
+    readCapacityQuantity,
+    capacityQuantityBytes,
+    readEnvironmentKey,
+    normalizeCapacityRequest,
+    normalizeDelivery,
+    normalizeObjectStorageRequest,
+    normalizeFilesystemStorageRequest,
+    normalizeStorageRequest,
+  };
+};