@lossless.org/client 1.19.0 → 1.20.1

package/ts/nosqldb/connectionstring.ts

@@ -0,0 +1,243 @@
+import * as plugins from './plugins.js';
+import type { ISmartdataDbOptions } from './classes.db.js';
+
+/** The options that locate and authenticate a database: everything a connection string is built from. */
+export type TSmartdataConnectionStringOptions = Pick<
+  ISmartdataDbOptions,
+  'mongoDbUrl' | 'mongoDbName' | 'mongoDbUser' | 'mongoDbPass'
+>;
+
+const redactionMarker = '<redacted>';
+
+/**
+ * The URL the driver connects with: `mongoDbUrl` with its first `<USERNAME>`/`<USER>`,
+ * `<PASSWORD>` and `<DBNAME>` placeholder of each case replaced by the URL-encoded
+ * user, password and the database name.
+ */
+export const buildSmartdataConnectionUrl = (optionsArg: TSmartdataConnectionStringOptions): string => {
+  const encodedUser = optionsArg.mongoDbUser ? encodeURIComponent(optionsArg.mongoDbUser) : '';
+  const encodedPass = optionsArg.mongoDbPass ? encodeURIComponent(optionsArg.mongoDbPass) : '';
+  return optionsArg.mongoDbUrl
+    .replace('<USERNAME>', encodedUser)
+    .replace('<username>', encodedUser)
+    .replace('<USER>', encodedUser)
+    .replace('<user>', encodedUser)
+    .replace('<PASSWORD>', encodedPass)
+    .replace('<password>', encodedPass)
+    .replace('<DBNAME>', optionsArg.mongoDbName || '')
+    .replace('<dbname>', optionsArg.mongoDbName || '');
+};
+
+/** Replaces every credential in a text an error carries. */
+type TRedact = (textArg: string) => string;
+
+/**
+ * The URI options whose value is a secret, by the driver's option table
+ * (`mongodb/src/connection_string.ts` `OPTIONS`): the `auth` credentials, the
+ * `authMechanismProperties` (for example `AWS_SESSION_TOKEN`), the SOCKS5 proxy
+ * login, the key file password, and the TLS key material the driver passes through.
+ * Lower-cased, because the driver reads option names case-insensitively.
+ */
+const secretUriOptionNames = new Set(
+  [
+    'auth',
+    'authMechanismProperties',
+    'proxyUsername',
+    'proxyPassword',
+    'tlsCertificateKeyFilePassword',
+    'key',
+    'passphrase',
+    'pfx',
+  ].map((nameArg) => nameArg.toLowerCase()),
+);
+
+/** Its value is a `KEY:value,KEY:value` list, and the driver quotes single values of it. */
+const mechanismPropertiesOptionName = 'authmechanismproperties';
+
+/**
+ * The `authMechanismProperties` entries whose value is a secret, by the driver's
+ * `AuthMechanismProperties` (`mongodb/src/cmap/auth/mongo_credentials.ts`).
+ */
+const secretMechanismPropertyNames = new Set(['AWS_SESSION_TOKEN']);
+
+/** A credential as written, URL-encoded, URL-decoded and query-decoded: a driver message may quote any of them. */
+const spellingsOf = (credentialArg: string): string[] => [
+  credentialArg,
+  ...[
+    encodeURIComponent,
+    decodeURIComponent,
+    (textArg: string) => decodeURIComponent(textArg.replaceAll('+', ' ')),
+  ].flatMap((transformArg) => {
+    try {
+      return [transformArg(credentialArg)];
+    } catch {
+      // A spelling the credential cannot be transformed into cannot be quoted either.
+      return [];
+    }
+  }),
+];
+
+/**
+ * The userinfo of a connection string, as a whole and as its user and password halves.
+ * A string the driver refuses is malformed by definition, so it is read generously:
+ * everything between `://` and the last `@`.
+ */
+const userinfoCredentialsOf = (urlArg: string): string[] => {
+  const userinfo = /^[^:/?#]*:\/\/(.*)@/s.exec(urlArg)?.[1];
+  if (userinfo === undefined) return [];
+  const separator = userinfo.indexOf(':');
+  return separator < 0
+    ? [userinfo]
+    : [userinfo, userinfo.slice(0, separator), userinfo.slice(separator + 1)];
+};
+
+interface IUriOption {
+  name: string;
+  value: string;
+}
+
+/**
+ * The `name=value` pairs of a connection string's query, read generously: a pair
+ * starts after any `?`, `&` or `;`, and its value runs to the next `&`, as the driver
+ * splits, and also to the next `;`, the legacy separator, so both readings are covered.
+ */
+const uriOptionsOf = (urlArg: string): IUriOption[] =>
+  [...urlArg.matchAll(/(?<=[?&;])([^?&;=]*)=(?=([^&]*))/g)].flatMap(([, name, value]) =>
+    [value, value.split(';')[0]].map((valueArg) => ({ name, value: valueArg })),
+  );
+
+/** The secret entry values in every spelling of an `authMechanismProperties` value, split as the driver splits it. */
+const secretMechanismPropertyValuesOf = (valueArg: string): string[] =>
+  spellingsOf(valueArg).flatMap((spellingArg) =>
+    spellingArg.split(',').flatMap((entryArg) => {
+      const separator = entryArg.indexOf(':');
+      return separator >= 0 && secretMechanismPropertyNames.has(entryArg.slice(0, separator).toUpperCase())
+        ? [entryArg.slice(separator + 1)]
+        : [];
+    }),
+  );
+
+/** The values of a connection string's secret-bearing URI options, under any spelling of their name. */
+const uriOptionCredentialsOf = (urlArg: string): string[] =>
+  uriOptionsOf(urlArg).flatMap(({ name, value }) => {
+    const names = spellingsOf(name).map((spellingArg) => spellingArg.toLowerCase());
+    if (!names.some((nameArg) => secretUriOptionNames.has(nameArg))) return [];
+    return names.includes(mechanismPropertiesOptionName) ? [value, ...secretMechanismPropertyValuesOf(value)] : [value];
+  });
+
+/**
+ * Every credential spelling the options carry, in the connection string as given and as
+ * built, longest first so the longest credential starting at a position is the one found.
+ */
+const connectionCredentialsOf = (optionsArg: TSmartdataConnectionStringOptions): string[] => {
+  const credentials = [
+    ...[optionsArg.mongoDbUrl, buildSmartdataConnectionUrl(optionsArg)].flatMap((urlArg) => [
+      ...userinfoCredentialsOf(urlArg),
+      ...uriOptionCredentialsOf(urlArg),
+    ]),
+    optionsArg.mongoDbUser,
+    optionsArg.mongoDbPass,
+  ].filter((credentialArg): credentialArg is string => Boolean(credentialArg));
+  return [...new Set(credentials.flatMap(spellingsOf))]
+    .filter((spellingArg) => spellingArg.length > 0)
+    .sort((leftArg, rightArg) => rightArg.length - leftArg.length);
+};
+
+// `RegExp.escape` is ES2025, beyond the ES2024 target.
+const escapeRegExp = (textArg: string): string => textArg.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+
+interface ISpan {
+  start: number;
+  end: number;
+}
+
+/**
+ * Where credentials occur in a text, overlapping occurrences merged into one span.
+ * The pattern only looks ahead, so it reports every start, overlapping ones included.
+ */
+const credentialSpansIn = (textArg: string, occurrenceArg: RegExp): ISpan[] => {
+  const spans: ISpan[] = [];
+  for (const { index, 1: credential } of textArg.matchAll(occurrenceArg)) {
+    const end = index + credential.length;
+    const previous = spans.at(-1);
+    if (previous !== undefined && index < previous.end) previous.end = Math.max(previous.end, end);
+    else spans.push({ start: index, end });
+  }
+  return spans;
+};
+
+const withSpansRedacted = (textArg: string, spansArg: readonly ISpan[]): string => {
+  let redacted = '';
+  let copiedUntil = 0;
+  for (const { start, end } of spansArg) {
+    redacted += textArg.slice(copiedUntil, start) + redactionMarker;
+    copiedUntil = end;
+  }
+  return redacted + textArg.slice(copiedUntil);
+};
+
+/**
+ * Redacts in one pass over the original text, so no credential is matched inside
+ * a marker another credential left and overlapping credentials leave no fragment.
+ */
+const redactorFor = (credentialsArg: readonly string[]): TRedact => {
+  if (credentialsArg.length === 0) return (textArg) => textArg;
+  const occurrence = new RegExp(`(?=(${credentialsArg.map(escapeRegExp).join('|')}))`, 'g');
+  return (textArg) => withSpansRedacted(textArg, credentialSpansIn(textArg, occurrence));
+};
+
+/** The fields a caller branches on: the driver's or Node's `code`, the server's `codeName`, the driver's error labels. */
+interface IPreservedErrorFields {
+  code?: number | string;
+  codeName?: string;
+  errorLabels?: string[];
+}
+
+/** Only these named fields: any other field, such as Node's `ERR_INVALID_URL` `input`, may hold the connection string. */
+const preservedFieldsOf = (errorArg: Error, redactArg: TRedact): IPreservedErrorFields => {
+  const fields: IPreservedErrorFields = {};
+  const code = 'code' in errorArg ? errorArg.code : undefined;
+  if (typeof code === 'number') fields.code = code;
+  if (typeof code === 'string') fields.code = redactArg(code);
+  const codeName = 'codeName' in errorArg ? errorArg.codeName : undefined;
+  if (typeof codeName === 'string') fields.codeName = redactArg(codeName);
+  if (errorArg instanceof plugins.mongodb.MongoError) fields.errorLabels = errorArg.errorLabels.map(redactArg);
+  return fields;
+};
+
+/**
+ * A copy of a thrown value that keeps its error name, its detail, its stack frames,
+ * its preserved fields, its cause chain and its aggregated errors, with every
+ * credential replaced. Only an error that is its own ancestor is left out, so a
+ * cyclic chain still ends.
+ */
+const copyRedacted = (
+  thrownArg: unknown,
+  redactArg: TRedact,
+  ancestorsArg: Set<Error>,
+): Error => {
+  if (!(thrownArg instanceof Error)) return new Error(redactArg(String(thrownArg)));
+  ancestorsArg.add(thrownArg);
+  const copyInner = (innerArg: unknown): Error[] =>
+    innerArg instanceof Error && ancestorsArg.has(innerArg) ? [] : [copyRedacted(innerArg, redactArg, ancestorsArg)];
+  const [cause] = thrownArg.cause === undefined ? [] : copyInner(thrownArg.cause);
+  const options = cause === undefined ? undefined : { cause };
+  const message = redactArg(thrownArg.message);
+  const copy = thrownArg instanceof AggregateError
+    ? new AggregateError(thrownArg.errors.flatMap((innerArg: unknown) => copyInner(innerArg)), message, options)
+    : new Error(message, options);
+  ancestorsArg.delete(thrownArg);
+  copy.name = redactArg(thrownArg.name);
+  if (thrownArg.stack !== undefined) copy.stack = redactArg(thrownArg.stack);
+  return Object.assign(copy, preservedFieldsOf(thrownArg, redactArg));
+};
+
+/**
+ * What a connection failure may show: the driver's error, copied with every
+ * credential of the options replaced by `<redacted>`. The original is never
+ * attached, because printing an error prints its whole cause chain.
+ */
+export const redactSmartdataConnectionError = (
+  thrownArg: unknown,
+  optionsArg: TSmartdataConnectionStringOptions,
+): Error => copyRedacted(thrownArg, redactorFor(connectionCredentialsOf(optionsArg)), new Set());