@lossless.org/nosqldb 8.0.0

package/ts/ts_nosqldb/resource-fencing.ts

@@ -0,0 +1,368 @@
+import * as plugins from './plugins.js';
+import type {
+  INoSqlDbDatabaseAllocationIdentity,
+  INoSqlDbDatabaseExport,
+} from './service-types.js';
+
+export type TNoSqlDbEffectivePayloadInputV1 =
+  | {
+      version: 1;
+      kind: 'smartdb.database.replace.v1';
+      databaseName: string;
+      source: INoSqlDbDatabaseExport;
+      /** Exact exclusive tenant owner; omission retains the legacy v1 digest. */
+      username?: string;
+      allocation?: INoSqlDbDatabaseAllocationIdentity;
+      holdPublication?: boolean;
+    }
+  | {
+      version: 1;
+      kind: 'smartdb.database.delete.v1';
+      databaseName: string;
+      username?: string;
+      allocation?: INoSqlDbDatabaseAllocationIdentity;
+      holdPublication?: boolean;
+    }
+  | {
+      version: 1;
+      kind: 'smartdb.database.ensure.v1';
+      databaseName: string;
+      username: string;
+      password: string;
+      roles?: string[];
+      allocation?: INoSqlDbDatabaseAllocationIdentity;
+    }
+  | {
+      version: 1;
+      kind: 'smartdb.database.allocate.v1';
+      databaseName: string;
+      expectedAbsent: true;
+      username: string;
+      password: string;
+      roles?: string[];
+    };
+
+type TCanonicalJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | TCanonicalJsonValue[]
+  | { [key: string]: TCanonicalJsonValue };
+
+const typedPayloadPrefix = plugins.buffer.Buffer.from(
+  'smartdb.effective-payload.typed.v1\0',
+  'utf8',
+);
+const minimumI64 = -9_223_372_036_854_775_808n;
+const maximumU64 = 18_446_744_073_709_551_615n;
+
+const compareUtf8Keys = (leftArg: string, rightArg: string): number =>
+  plugins.buffer.Buffer.compare(
+    plugins.buffer.Buffer.from(leftArg, 'utf8'),
+    plugins.buffer.Buffer.from(rightArg, 'utf8'),
+  );
+
+const formatSerdeJsonFloat = (valueArg: number): string => {
+  const transportNumber = JSON.stringify(valueArg);
+  if (/^-?\d+$/.test(transportNumber)) {
+    const integer = BigInt(transportNumber);
+    if (integer >= minimumI64 && integer <= maximumU64) {
+      return transportNumber;
+    }
+  }
+
+  const negative = valueArg < 0;
+  const source = Math.abs(valueArg).toString().toLowerCase();
+  let digits: string;
+  let decimalExponent: number;
+  if (source.includes('e')) {
+    const [coefficient, exponent] = source.split('e');
+    digits = coefficient.replace('.', '').replace(/^0+|0+$/g, '');
+    decimalExponent = Number.parseInt(exponent, 10);
+  } else {
+    const [integerPart, fractionPart = ''] = source.split('.');
+    const rawDigits = `${integerPart}${fractionPart}`;
+    const firstSignificant = rawDigits.search(/[1-9]/);
+    const lastSignificant = rawDigits.search(/[1-9](?!.*[1-9])/);
+    if (firstSignificant < 0) {
+      return '0.0';
+    }
+    digits = rawDigits.slice(firstSignificant, lastSignificant + 1);
+    decimalExponent = integerPart.length - firstSignificant - 1;
+  }
+
+  let rendered: string;
+  if (decimalExponent >= -5 && decimalExponent <= 15) {
+    const integerDigits = decimalExponent + 1;
+    if (digits.length <= integerDigits) {
+      rendered = `${digits}${'0'.repeat(integerDigits - digits.length)}.0`;
+    } else if (integerDigits > 0) {
+      rendered = `${digits.slice(0, integerDigits)}.${digits.slice(integerDigits)}`;
+    } else {
+      rendered = `0.${'0'.repeat(-integerDigits)}${digits}`;
+    }
+  } else {
+    const significand =
+      digits.length === 1 ? digits : `${digits[0]}.${digits.slice(1)}`;
+    rendered = `${significand}e${decimalExponent >= 0 ? '+' : ''}${decimalExponent}`;
+  }
+  return negative ? `-${rendered}` : rendered;
+};
+
+const canonicalJsonStringify = (valueArg: TCanonicalJsonValue): string => {
+  if (typeof valueArg === 'number') {
+    return formatSerdeJsonFloat(valueArg);
+  }
+  if (valueArg === null || typeof valueArg !== 'object') {
+    const serialized = JSON.stringify(valueArg);
+    if (serialized === undefined) {
+      throw new TypeError('NoSQLDB effective payload contains unsupported JSON');
+    }
+    return serialized;
+  }
+  if (Array.isArray(valueArg)) {
+    return `[${valueArg.map((entryArg) => canonicalJsonStringify(entryArg)).join(',')}]`;
+  }
+  return `{${Object.keys(valueArg)
+    .map(
+      (keyArg) =>
+        `${JSON.stringify(keyArg)}:${canonicalJsonStringify(valueArg[keyArg])}`,
+    )
+    .join(',')}}`;
+};
+
+const encodeTypedLength = (lengthArg: number): Uint8Array => {
+  const encoded = plugins.buffer.Buffer.allocUnsafe(8);
+  encoded.writeBigUInt64BE(BigInt(lengthArg));
+  return encoded;
+};
+
+const encodeTypedBytes = (valueArg: Uint8Array): Uint8Array[] => [
+  encodeTypedLength(valueArg.byteLength),
+  valueArg,
+];
+
+const encodeTypedValue = (
+  valueArg: TCanonicalJsonValue,
+  chunksArg: Uint8Array[],
+): void => {
+  if (valueArg === null) {
+    chunksArg.push(plugins.buffer.Buffer.from([0]));
+    return;
+  }
+  if (valueArg === false) {
+    chunksArg.push(plugins.buffer.Buffer.from([1]));
+    return;
+  }
+  if (valueArg === true) {
+    chunksArg.push(plugins.buffer.Buffer.from([2]));
+    return;
+  }
+  if (typeof valueArg === 'number') {
+    if (!Number.isFinite(valueArg)) {
+      throw new TypeError('NoSQLDB exact replace contains a non-finite number');
+    }
+    const encoded = plugins.buffer.Buffer.allocUnsafe(9);
+    encoded[0] = 3;
+    encoded.writeDoubleBE(valueArg, 1);
+    chunksArg.push(encoded);
+    return;
+  }
+  if (typeof valueArg === 'string') {
+    const encoded = plugins.buffer.Buffer.from(valueArg, 'utf8');
+    chunksArg.push(plugins.buffer.Buffer.from([4]), ...encodeTypedBytes(encoded));
+    return;
+  }
+  if (Array.isArray(valueArg)) {
+    chunksArg.push(
+      plugins.buffer.Buffer.from([5]),
+      encodeTypedLength(valueArg.length),
+    );
+    for (const value of valueArg) {
+      encodeTypedValue(value, chunksArg);
+    }
+    return;
+  }
+  const keys = Object.keys(valueArg).sort(compareUtf8Keys);
+  chunksArg.push(
+    plugins.buffer.Buffer.from([6]),
+    encodeTypedLength(keys.length),
+  );
+  for (const key of keys) {
+    const encodedKey = plugins.buffer.Buffer.from(key, 'utf8');
+    chunksArg.push(
+      plugins.buffer.Buffer.from([4]),
+      ...encodeTypedBytes(encodedKey),
+    );
+    encodeTypedValue(valueArg[key], chunksArg);
+  }
+};
+
+const encodeTypedPayload = (valueArg: TCanonicalJsonValue): Uint8Array => {
+  const chunks: Uint8Array[] = [typedPayloadPrefix];
+  encodeTypedValue(valueArg, chunks);
+  return plugins.buffer.Buffer.concat(chunks);
+};
+
+/**
+ * Computes the provider-derived SHA-256 identity for NoSQLDB's version 1
+ * fenced replace, exact-user delete, and exact-user ensure payload profiles.
+ */
+export const createNoSqlDbEffectivePayloadSha256V1 = (
+  inputArg: TNoSqlDbEffectivePayloadInputV1,
+): string => {
+  if (inputArg.version !== 1) {
+    throw new TypeError('NoSQLDB effective payload version must be 1');
+  }
+  if (typeof inputArg.databaseName !== 'string') {
+    throw new TypeError('NoSQLDB effective payload databaseName must be a string');
+  }
+
+  let effectivePayload: object;
+  let useTypedEncoding = false;
+  switch (inputArg.kind) {
+    case 'smartdb.database.replace.v1':
+      if (
+        inputArg.username !== undefined &&
+        typeof inputArg.username !== 'string'
+      ) {
+        throw new TypeError('NoSQLDB exact replace username must be a string');
+      }
+      if (
+        inputArg.holdPublication !== undefined &&
+        typeof inputArg.holdPublication !== 'boolean'
+      ) {
+        throw new TypeError('NoSQLDB holdPublication must be a Boolean');
+      }
+      effectivePayload = {
+        version: 1,
+        kind: inputArg.kind,
+        databaseName: inputArg.databaseName,
+        source: inputArg.source,
+        ...(inputArg.username === undefined
+          ? {}
+          : { username: inputArg.username }),
+        ...(inputArg.allocation === undefined
+          ? {}
+          : { allocation: inputArg.allocation }),
+        ...(inputArg.holdPublication === true
+          ? { holdPublication: true }
+          : {}),
+      };
+      useTypedEncoding =
+        inputArg.username !== undefined ||
+        inputArg.allocation !== undefined ||
+        inputArg.holdPublication === true;
+      break;
+    case 'smartdb.database.ensure.v1': {
+      if (typeof inputArg.username !== 'string') {
+        throw new TypeError('NoSQLDB exact ensure username must be a string');
+      }
+      if (typeof inputArg.password !== 'string') {
+        throw new TypeError('NoSQLDB exact ensure password must be a string');
+      }
+      const roles = inputArg.roles ?? ['readWrite', 'dbAdmin'];
+      if (
+        !Array.isArray(roles) ||
+        roles.some(
+          (roleArg) => typeof roleArg !== 'string' || roleArg.length === 0,
+        )
+      ) {
+        throw new TypeError(
+          'NoSQLDB exact ensure roles must be an array of non-empty strings',
+        );
+      }
+      const canonicalRoles = [...new Set(roles)].sort(compareUtf8Keys);
+      effectivePayload = {
+        version: 1,
+        kind: inputArg.kind,
+        databaseName: inputArg.databaseName,
+        username: inputArg.username,
+        passwordSha256: plugins.crypto
+          .createHash('sha256')
+          .update(inputArg.password, 'utf8')
+          .digest('hex'),
+        roles: canonicalRoles,
+        ...(inputArg.allocation === undefined
+          ? {}
+          : { allocation: inputArg.allocation }),
+      };
+      useTypedEncoding = inputArg.allocation !== undefined;
+      break;
+    }
+    case 'smartdb.database.allocate.v1': {
+      if (inputArg.expectedAbsent !== true) {
+        throw new TypeError('NoSQLDB allocation expectedAbsent must be true');
+      }
+      if (typeof inputArg.username !== 'string') {
+        throw new TypeError('NoSQLDB allocation username must be a string');
+      }
+      if (typeof inputArg.password !== 'string') {
+        throw new TypeError('NoSQLDB allocation password must be a string');
+      }
+      const roles = inputArg.roles ?? ['readWrite', 'dbAdmin'];
+      if (!Array.isArray(roles) || roles.some((roleArg) => typeof roleArg !== 'string' || roleArg.length === 0)) {
+        throw new TypeError('NoSQLDB allocation roles must be an array of non-empty strings');
+      }
+      effectivePayload = {
+        version: 1,
+        kind: inputArg.kind,
+        databaseName: inputArg.databaseName,
+        expectedAbsent: true,
+        username: inputArg.username,
+        passwordSha256: plugins.crypto
+          .createHash('sha256')
+          .update(inputArg.password, 'utf8')
+          .digest('hex'),
+        roles: [...new Set(roles)].sort(compareUtf8Keys),
+      };
+      useTypedEncoding = true;
+      break;
+    }
+    case 'smartdb.database.delete.v1':
+      if (
+        inputArg.username !== undefined &&
+        typeof inputArg.username !== 'string'
+      ) {
+        throw new TypeError('NoSQLDB exact delete username must be a string when supplied');
+      }
+      if (
+        inputArg.holdPublication !== undefined &&
+        typeof inputArg.holdPublication !== 'boolean'
+      ) {
+        throw new TypeError('NoSQLDB holdPublication must be a Boolean');
+      }
+      effectivePayload = {
+        version: 1,
+        kind: inputArg.kind,
+        databaseName: inputArg.databaseName,
+        ...(inputArg.username === undefined
+          ? { rawDatabaseOnly: true }
+          : { username: inputArg.username, rawDatabaseOnly: false }),
+        ...(inputArg.allocation === undefined
+          ? {}
+          : { allocation: inputArg.allocation }),
+        ...(inputArg.holdPublication === true
+          ? { holdPublication: true }
+          : {}),
+      };
+      useTypedEncoding = inputArg.allocation !== undefined;
+      break;
+    default:
+      throw new TypeError('NoSQLDB mutation kind has no version 1 payload profile');
+  }
+
+  const transportJson = JSON.stringify(effectivePayload);
+  if (transportJson === undefined) {
+    throw new TypeError('NoSQLDB effective payload cannot be encoded as JSON');
+  }
+  const normalizedPayload = JSON.parse(transportJson) as TCanonicalJsonValue;
+  const encodedPayload = useTypedEncoding
+    ? encodeTypedPayload(normalizedPayload)
+    : canonicalJsonStringify(normalizedPayload);
+  return plugins.crypto
+    .createHash('sha256')
+    .update(encodedPayload)
+    .digest('hex');
+};