@serve.zone/interfaces 32.1.0 → 32.2.0

package/ts/platform/storage.ts

@@ -1,4 +1,9 @@
 import type { TSecretManagementScope } from '../data/secret.js';
+import {
+  canonicalizeStrictJson,
+  createCanonicalJsonSha256Hex,
+} from '../private/canonicaljson.js';
+import { createStorageContractReaders } from '../private/storagecontract.js';
 
 /**
  * Backend-neutral storage vocabulary shared by App Store manifests, control
@@ -186,8 +191,12 @@ export interface IResolvedStorageBindingBase {
   /** Stable App Store storageRequests[].id. */
   requestId: string;
   /**
-   * Canonical digest of the normalized request. Adapters use it to distinguish
-   * an idempotent reconciliation from a migration.
+   * Canonical digest of the normalized request, exactly as
+   * `createStorageRequestSha256` states it: bare lowercase hex over the request
+   * alone. Adapters use it to distinguish an idempotent reconciliation from a
+   * migration, and a consumer re-derives it to recognise the request it asked
+   * for, so the control plane and the consumer call that one function rather
+   * than each deriving a value the other cannot reproduce.
    */
   requestDigest: string;
   kind: TStorageResourceKind;
@@ -232,3 +241,51 @@ extends IResolvedStorageBindingBase {
 export type TResolvedStorageBinding =
   | IResolvedFilesystemStorageBinding
   | IResolvedObjectStorageBinding;
+
+export class StorageContractError extends Error {
+  public constructor(reasonArg: string) {
+    super(`storage contract error: ${reasonArg}`);
+    this.name = 'StorageContractError';
+  }
+}
+
+const fail = (reasonArg: string): never => {
+  throw new StorageContractError(reasonArg);
+};
+
+const { normalizeStorageRequest } = createStorageContractReaders(fail);
+
+/**
+ * The exact bytes a storage request's digest is taken over: the request normalized to its contract
+ * shape, written as strict canonical JSON — keys in UTF-16 code-unit order, no whitespace, no
+ * absent member carried as `null`.
+ *
+ * Anything that is not a storage request is refused rather than hashed, because a digest of an
+ * unjudged body would name a request no adapter could fulfil.
+ */
+export const canonicalizeStorageRequest = (valueArg: unknown): string => {
+  return canonicalizeStrictJson(
+    normalizeStorageRequest(valueArg, 'storage request'),
+    fail,
+  );
+};
+
+/**
+ * The storage request digest: bare lowercase hex SHA-256 over the canonical request, with no
+ * prefix and nothing but the request in the hashed value.
+ *
+ * A control plane issues this value on a binding and a consumer re-derives it from the request it
+ * declared; the two only agree because they call this one function. A second derivation elsewhere
+ * — a prefix, or a wrapper object around the request — is a different value for the same binding,
+ * and the consumer would keep rejecting a binding that is in fact its own.
+ */
+export const createStorageRequestSha256 = async (
+  valueArg: unknown,
+): Promise<string> => {
+  return createCanonicalJsonSha256Hex(canonicalizeStorageRequest(valueArg), fail);
+};
+
+export {
+  storageRequestCanonicalDigestGoldenVectors,
+  type IStorageRequestCanonicalDigestGoldenVector,
+} from './storage.golden.js';

package/ts/platform/storagemigration.ts

@@ -8,6 +8,10 @@ import {
   deepFreezeValue,
   strictCanonicalJsonRules,
 } from '../private/canonicaljson.js';
+import {
+  createStorageContractReaders,
+  storageContractStringLimits,
+} from '../private/storagecontract.js';
 import type {
   IResolvedObjectStorageBinding,
   IResolvedStoragePolicyRef,
@@ -16,11 +20,13 @@ import type {
 
 export const storageMigrationContractLimits = Object.freeze({
   maximumControlJsonBytes: 256 * 1024,
-  maximumConfiguredStringBytes: 2048,
+  maximumConfiguredStringBytes:
+    storageContractStringLimits.maximumConfiguredStringBytes,
   maximumIssueMessageBytes: 4096,
   maximumAbortReasonBytes: 4096,
-  maximumEnvironmentKeyBytes: 256,
-  maximumSecretPathBytes: 2048,
+  maximumEnvironmentKeyBytes:
+    storageContractStringLimits.maximumEnvironmentKeyBytes,
+  maximumSecretPathBytes: storageContractStringLimits.maximumSecretPathBytes,
 });
 
 export const storageMigrationCanonicalJsonRules = strictCanonicalJsonRules;
@@ -408,9 +414,28 @@ const fail = (reasonArg: string): never => {
   throw new StorageMigrationContractError(reasonArg);
 };
 
-const utf8ByteLength = (valueArg: string): number => {
-  return new TextEncoder().encode(valueArg).byteLength;
-};
+/**
+ * The storage contract's readers, reporting every refusal as a migration contract error. The
+ * request a migration targets is the same request a control plane reconciles, so it is judged by
+ * the same rules and, through them, digests to the same bytes.
+ */
+const {
+  utf8ByteLength,
+  readRecord,
+  readDenseArray,
+  assertKeys,
+  assertExactKeys,
+  readString,
+  readIdentifier,
+  readSha256,
+  readSafeInteger,
+  readBoolean,
+  readLiteral,
+  readCapacityQuantity,
+  capacityQuantityBytes,
+  normalizeDelivery,
+  normalizeObjectStorageRequest,
+} = createStorageContractReaders(fail);
 
 /**
  * Enforce this against Content-Length and the running request byte count
@@ -427,200 +452,6 @@ export const assertStorageMigrationControlIngressByteLength = (
   );
 };
 
-const readRecord = (
-  valueArg: unknown,
-  fieldNameArg: string,
-): Record<string, unknown> => {
-  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
-    return fail(`${fieldNameArg} must be a plain object`);
-  }
-  const prototype = Object.getPrototypeOf(valueArg);
-  if (prototype !== Object.prototype && prototype !== null) {
-    return fail(`${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 fail(`${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 fail(
-        `${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 fail(`${fieldNameArg} must be a dense plain array`);
-  }
-  if (
-    valueArg.length < minimumLengthArg ||
-    valueArg.length > maximumLengthArg
-  ) {
-    return fail(
-      `${fieldNameArg} must contain between ${minimumLengthArg} and ${maximumLengthArg} entries`,
-    );
-  }
-  for (let index = 0; index < valueArg.length; index++) {
-    if (!Object.hasOwn(valueArg, index)) {
-      return fail(`${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 fail(
-        `${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 fail(`${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))
-  ) {
-    fail(`${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 =
-    storageMigrationContractLimits.maximumConfiguredStringBytes,
-): string => {
-  if (
-    typeof valueArg !== 'string' ||
-    valueArg.length === 0 ||
-    utf8ByteLength(valueArg) > maximumBytesArg ||
-    /[\u0000-\u001f\u007f]/u.test(valueArg)
-  ) {
-    return fail(`${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 fail(`${fieldNameArg} contains an unpaired UTF-16 surrogate`);
-      }
-      index++;
-    } else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
-      return fail(`${fieldNameArg} contains an unpaired UTF-16 surrogate`);
-    }
-  }
-  return valueArg;
-};
-
-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)$/;
-
-const readIdentifier = (valueArg: unknown, fieldNameArg: string): string => {
-  if (typeof valueArg !== 'string' || !canonicalIdPattern.test(valueArg)) {
-    return fail(`${fieldNameArg} must be a canonical identifier`);
-  }
-  return valueArg;
-};
-
-const readSha256 = (valueArg: unknown, fieldNameArg: string): string => {
-  if (typeof valueArg !== 'string' || !sha256Pattern.test(valueArg)) {
-    return fail(`${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 fail(
-      `${fieldNameArg} must be a safe integer between ${minimumArg} and ${maximumArg}`,
-    );
-  }
-  return valueArg;
-};
-
-const readBoolean = (valueArg: unknown, fieldNameArg: string): boolean => {
-  if (typeof valueArg !== 'boolean') {
-    return fail(`${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 fail(`${fieldNameArg} is outside the supported values`);
-  }
-  return valueArg as TLiteral;
-};
-
 const canonicalize = (valueArg: unknown): string => {
   return canonicalizeStrictJson(valueArg, fail);
 };
@@ -777,50 +608,6 @@ const normalizeStorageClass = (
   };
 };
 
-const readCapacityQuantity = (
-  valueArg: unknown,
-  fieldNameArg: string,
-): string => {
-  if (typeof valueArg !== 'string' || !capacityPattern.test(valueArg)) {
-    return fail(`${fieldNameArg} must be a canonical base-2 capacity quantity`);
-  }
-  const numericPart = valueArg.replace(/(?:KiB|MiB|GiB|TiB)$/, '');
-  if (!Number.isSafeInteger(Number(numericPart))) {
-    return fail(`${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<IAppStoreObjectStorageRequest['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 fail(`${fieldNameArg}.limit must be at least request`);
-  }
-  return {
-    request,
-    ...(limit ? { limit } : {}),
-  };
-};
-
 const normalizeResolvedCapacity = (
   valueArg: unknown,
   fieldNameArg: string,
@@ -867,102 +654,6 @@ const normalizeResolvedCapacity = (
   };
 };
 
-const readEnvironmentKey = (
-  valueArg: unknown,
-  fieldNameArg: string,
-): string => {
-  if (
-    typeof valueArg !== 'string' ||
-    utf8ByteLength(valueArg) >
-      storageMigrationContractLimits.maximumEnvironmentKeyBytes ||
-    !environmentKeyPattern.test(valueArg)
-  ) {
-    return fail(`${fieldNameArg} must be a canonical environment key`);
-  }
-  return valueArg;
-};
-
-const normalizeDelivery = (
-  valueArg: unknown,
-  fieldNameArg: string,
-): IResolvedObjectStorageBinding['delivery'] => {
-  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 fail(`${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`,
-      storageMigrationContractLimits.maximumSecretPathBytes,
-    );
-    if (
-      !targetPath.startsWith('/run/secrets/') ||
-      targetPath.includes('\\') ||
-      targetPath.split('/').some((segmentArg) =>
-        segmentArg === '.' || segmentArg === '..'
-      )
-    ) {
-      return fail(
-        `${fieldNameArg}.targetPath must be a canonical path below /run/secrets`,
-      );
-    }
-    if (value.format !== 'servezone-object-storage') {
-      return fail(`${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
-        : fail(`${fieldNameArg}.mode must be 0400 or 0440`),
-    };
-  }
-  return fail(`${fieldNameArg}.type is unsupported`);
-};
-
 const normalizeCredentialManagementScope = (
   valueArg: unknown,
   fieldNameArg: string,
@@ -974,106 +665,6 @@ const normalizeCredentialManagementScope = (
   return value as IResolvedObjectStorageBinding['credentialManagementScope'];
 };
 
-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 fail(`${fieldNameArg} must not be empty`);
-  }
-  return {
-    ...(Object.hasOwn(value, 'backup')
-      ? {
-          backup: value.backup === 'required'
-            ? 'required' as const
-            : fail(`${fieldNameArg}.backup must be required`),
-        }
-      : {}),
-    ...(Object.hasOwn(value, 'versioning')
-      ? {
-          versioning: value.versioning === 'required'
-            ? 'required' as const
-            : fail(`${fieldNameArg}.versioning must be required`),
-        }
-      : {}),
-    ...(Object.hasOwn(value, 'retentionDays')
-      ? {
-          retentionDays: readSafeInteger(
-            value.retentionDays,
-            `${fieldNameArg}.retentionDays`,
-            1,
-            365_000,
-          ),
-        }
-      : {}),
-  };
-};
-
-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 fail(`${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 normalizeCapabilities = (
   valueArg: unknown,
   fieldNameArg: string,