@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/api-validation.js

@@ -0,0 +1,543 @@
+'use strict';
+
+const DEFAULT_REJECTED_STRING_MAX = 120;
+const DEFAULT_IDENTIFIER_MAX = 128;
+const MAX_ALLOWED_VALUES = 50;
+const API_INPUT_ERROR_DETAILS_MAX = 50;
+const API_INPUT_ERROR_MARKER = Symbol.for('minions.apiInputError');
+const SECRET_DETAIL_MARKER = Symbol('minions.secretDetail');
+// Credential-shaped field/path tokens. Aligned with the repository's env-key
+// deny patterns (engine/shared.js#ENGINE_DEFAULTS.managedSpawn.envKeyDenyPatterns:
+// _SECRET, _TOKEN, _API_KEY, _PASSWORD, _PASSWD, _CREDENTIALS, _AUTH, _PAT, …) so
+// short credential names such as `pat`, `auth`, and `passwd` are redacted. Matched
+// against camelCase/underscore/kebab TOKENS (not raw substrings) so ordinary
+// fields that merely contain a token as a substring — `path` (contains "pat"),
+// `author` (contains "auth") — are NOT redacted.
+const SECRET_FIELD_TOKENS = new Set([
+  'password', 'passwd', 'passphrase', 'pwd',
+  'secret', 'secrets', 'clientsecret',
+  'token', 'tokens', 'accesstoken', 'refreshtoken', 'idtoken', 'bearer',
+  'apikey', 'apikeys', 'accesskey', 'privatekey', 'secretkey',
+  'authorization', 'auth', 'oauth',
+  'credential', 'credentials',
+  'cookie', 'session', 'sessionid',
+  'pat', 'signature', 'sig',
+]);
+// Adjacent-token pairs that only read as credential-shaped once joined
+// (`api key` → apikey, `access key` → accesskey, `private key` → privatekey,
+// `client secret` → clientsecret, `refresh token` → refreshtoken).
+const SECRET_TOKEN_PAIRS = new Set([
+  'apikey', 'accesskey', 'privatekey', 'secretkey', 'clientsecret',
+  'accesstoken', 'refreshtoken', 'idtoken', 'sessionid',
+]);
+const DEFAULT_IDENTIFIER_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+function _splitFieldTokens(text) {
+  return String(text == null ? '' : text)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')      // camelCase boundary
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')   // ACRONYMWord boundary
+    .split(/[^A-Za-z0-9]+/)                       // separators (._-/ space …)
+    .map(token => token.toLowerCase())
+    .filter(Boolean);
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function normalizeCode(value, fallback) {
+  const code = typeof value === 'string' ? value.trim() : '';
+  return /^[a-z][a-z0-9-]*$/.test(code) ? code : fallback;
+}
+
+function normalizePath(path) {
+  if (Array.isArray(path)) {
+    let result = '';
+    for (const segment of path) {
+      if (Number.isInteger(segment) && segment >= 0) {
+        result += `[${segment}]`;
+        continue;
+      }
+      const part = String(segment == null ? '' : segment).trim();
+      if (!part) continue;
+      result += result ? `.${part}` : part;
+    }
+    return result.slice(0, 256);
+  }
+  return typeof path === 'string' ? path.trim().slice(0, 256) : '';
+}
+
+function fieldFromPath(path) {
+  if (Array.isArray(path)) {
+    for (let i = path.length - 1; i >= 0; i -= 1) {
+      if (typeof path[i] === 'string' && path[i].trim()) return path[i].trim().slice(0, 128);
+    }
+  }
+  const normalized = normalizePath(path);
+  if (!normalized) return '';
+  const match = normalized.match(/(?:^|\.)([^.[\]]+)(?:\[\d+\])?$/);
+  return match ? match[1].slice(0, 128) : '';
+}
+
+function isSecretLikePath(path, field) {
+  const parts = [];
+  if (Array.isArray(path)) {
+    for (const segment of path) parts.push(String(segment == null ? '' : segment));
+  } else {
+    parts.push(String(path == null ? '' : path));
+  }
+  parts.push(String(field == null ? '' : field));
+  for (const part of parts) {
+    const tokens = _splitFieldTokens(part);
+    for (let i = 0; i < tokens.length; i += 1) {
+      if (SECRET_FIELD_TOKENS.has(tokens[i])) return true;
+      if (i + 1 < tokens.length && SECRET_TOKEN_PAIRS.has(tokens[i] + tokens[i + 1])) return true;
+    }
+  }
+  return false;
+}
+
+function boundedString(value, maxLength) {
+  const text = String(value);
+  const max = Number.isInteger(maxLength) && maxLength > 0
+    ? maxLength
+    : DEFAULT_REJECTED_STRING_MAX;
+  return text.length <= max ? text : `${text.slice(0, max)}...`;
+}
+
+function existingContainerSummary(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const keys = Object.keys(value);
+  if ((value.type === 'array' || value.type === 'buffer')
+      && keys.length === 2
+      && keys.includes('length')
+      && Number.isInteger(value.length)
+      && value.length >= 0) {
+    return { type: value.type, length: value.length };
+  }
+  if (value.type === 'object'
+      && keys.length === 2
+      && keys.includes('keyCount')
+      && Number.isInteger(value.keyCount)
+      && value.keyCount >= 0) {
+    return { type: 'object', keyCount: value.keyCount };
+  }
+  return null;
+}
+
+function summarizeRejectedValue(value, options = {}) {
+  if (options.secret === true || isSecretLikePath(options.path, options.field)) return '[REDACTED]';
+  if (value === null) return null;
+  if (value === undefined) return '[undefined]';
+  if (typeof value === 'string') return boundedString(value, options.maxStringLength);
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : `[${String(value)}]`;
+  if (typeof value === 'bigint') return boundedString(`${value}n`, options.maxStringLength);
+  if (typeof value === 'symbol') return '[symbol]';
+  if (typeof value === 'function') return '[function]';
+  const priorSummary = existingContainerSummary(value);
+  if (priorSummary) return priorSummary;
+  if (Buffer.isBuffer(value)) return { type: 'buffer', length: value.length };
+  if (Array.isArray(value)) return { type: 'array', length: value.length };
+  if (typeof value === 'object') {
+    let keyCount = 0;
+    try { keyCount = Object.keys(value).length; } catch {}
+    return { type: 'object', keyCount };
+  }
+  return boundedString(value, options.maxStringLength);
+}
+
+function summarizeAllowedValues(values, options = {}) {
+  if (!Array.isArray(values)
+      || options.secret === true
+      || isSecretLikePath(options.path, options.field)) return undefined;
+  return values.slice(0, MAX_ALLOWED_VALUES).map(value => (
+    summarizeRejectedValue(value, { maxStringLength: 80 })
+  ));
+}
+
+function normalizeDetail(detail, defaults = {}) {
+  const source = detail && typeof detail === 'object' && !Array.isArray(detail)
+    ? detail
+    : {};
+  const rawPath = source.path !== undefined ? source.path : defaults.path;
+  const rawField = source.field !== undefined
+    ? source.field
+    : (defaults.field || fieldFromPath(rawPath));
+  const secret = source[SECRET_DETAIL_MARKER] === true
+    || source.secret === true
+    || isSecretLikePath(rawPath, rawField);
+  const path = normalizePath(rawPath);
+  const field = String(rawField).trim().slice(0, 128);
+  const code = normalizeCode(source.code, normalizeCode(defaults.code, 'invalid-input'));
+  const message = boundedString(
+    source.message !== undefined ? source.message : (defaults.message || 'Invalid input'),
+    500,
+  );
+  const normalized = { code, message };
+  if (secret) Object.defineProperty(normalized, SECRET_DETAIL_MARKER, { value: true });
+  if (field) normalized.field = field;
+  if (path) normalized.path = path;
+  if (typeof source.expected === 'string' && source.expected.trim()) {
+    normalized.expected = source.expected.trim().slice(0, 120);
+  }
+  if (hasOwn(source, 'rejectedValue')) {
+    normalized.rejectedValue = summarizeRejectedValue(source.rejectedValue, {
+      path,
+      field,
+      secret,
+      maxStringLength: source.maxRejectedStringLength,
+    });
+  }
+  const allowedValues = summarizeAllowedValues(source.allowedValues, { path, field, secret });
+  if (allowedValues) normalized.allowedValues = allowedValues;
+  for (const key of ['min', 'max', 'minLength', 'maxLength']) {
+    if (Number.isFinite(source[key])) normalized[key] = source[key];
+  }
+  if (typeof source.inclusiveMin === 'boolean') normalized.inclusiveMin = source.inclusiveMin;
+  if (typeof source.inclusiveMax === 'boolean') normalized.inclusiveMax = source.inclusiveMax;
+  return normalized;
+}
+
+class ApiInputError extends Error {
+  constructor(message, options = {}) {
+    const safeMessage = boundedString(message || 'Invalid input', 500);
+    super(safeMessage);
+    this.name = 'ApiInputError';
+    this.code = normalizeCode(options.code, 'invalid-input');
+    this.statusCode = Number.isInteger(options.statusCode)
+      && options.statusCode >= 400
+      && options.statusCode < 500
+      ? options.statusCode
+      : 400;
+    Object.defineProperty(this, API_INPUT_ERROR_MARKER, { value: true });
+
+    const suppliedDetails = Array.isArray(options.details) ? options.details : [];
+    const hasInlineDetail = ['field', 'path', 'expected', 'rejectedValue', 'allowedValues', 'min', 'max', 'minLength', 'maxLength']
+      .some(key => hasOwn(options, key));
+    const rawDetails = suppliedDetails.length
+      ? suppliedDetails
+      : (hasInlineDetail ? [options] : []);
+    this.details = rawDetails.slice(0, API_INPUT_ERROR_DETAILS_MAX).map(detail => normalizeDetail(detail, {
+      code: this.code,
+      message: safeMessage,
+      field: options.field,
+      path: options.path,
+    }));
+
+    const first = this.details[0];
+    if (first) {
+      for (const key of ['field', 'path', 'rejectedValue', 'allowedValues', 'expected', 'min', 'max', 'minLength', 'maxLength']) {
+        if (hasOwn(first, key)) this[key] = first[key];
+      }
+    }
+    if (options.cause !== undefined) this.cause = options.cause;
+  }
+}
+
+function isApiInputError(error) {
+  return !!(error && (error instanceof ApiInputError || error[API_INPUT_ERROR_MARKER] === true));
+}
+
+function statusBearingCode(error) {
+  return error instanceof Error
+    && Number.isInteger(error.statusCode)
+    && error.statusCode >= 400
+    && error.statusCode <= 599
+    ? error.statusCode
+    : null;
+}
+
+function exposedErrorDetails(error) {
+  if (!Array.isArray(error && error.details)) return [];
+  return error.details
+    .filter(detail => detail && typeof detail === 'object' && !Array.isArray(detail))
+    .slice(0, API_INPUT_ERROR_DETAILS_MAX)
+    .map(detail => normalizeDetail(detail, {
+      code: error.code,
+      message: error.message,
+      field: error.field,
+      path: error.path,
+    }));
+}
+
+function exposedEnvelope(error, fallbackCode) {
+  const message = boundedString(error && error.message ? error.message : 'Request failed', 500);
+  const code = normalizeCode(error && error.code, fallbackCode);
+  const body = { error: message, code };
+  const details = exposedErrorDetails(error);
+  if (details.length) {
+    body.details = details;
+    const first = details[0];
+    for (const key of ['field', 'path', 'rejectedValue', 'allowedValues', 'expected', 'min', 'max', 'minLength', 'maxLength']) {
+      if (hasOwn(first, key)) body[key] = first[key];
+    }
+  }
+  return body;
+}
+
+function toApiErrorResponse(error) {
+  if (isApiInputError(error)) {
+    return {
+      statusCode: error.statusCode,
+      body: exposedEnvelope(error, 'invalid-input'),
+    };
+  }
+  const statusCode = statusBearingCode(error);
+  if (statusCode !== null) {
+    if (statusCode >= 500) {
+      return {
+        statusCode,
+        body: {
+          error: 'Internal server error',
+          code: 'internal-error',
+        },
+      };
+    }
+    return {
+      statusCode,
+      body: exposedEnvelope(error, 'request-failed'),
+    };
+  }
+  return {
+    statusCode: 500,
+    body: {
+      error: 'Internal server error',
+      code: 'internal-error',
+    },
+  };
+}
+
+function buildApiErrorEnvelope(error) {
+  return toApiErrorResponse(error).body;
+}
+
+function optionalValue(value, options) {
+  if (value === undefined && options.optional === true) return true;
+  if (value === null && options.nullable === true) return true;
+  return false;
+}
+
+function validationLabel(options) {
+  return normalizePath(options.path) || options.field || 'value';
+}
+
+function validationError(value, options, defaults, extra = {}) {
+  const message = options.message || `${validationLabel(options)} ${defaults.expectation}`;
+  throw new ApiInputError(message, {
+    code: options.code || defaults.code,
+    statusCode: options.statusCode,
+    field: options.field,
+    path: options.path !== undefined ? options.path : options.field,
+    expected: defaults.expected,
+    rejectedValue: value,
+    ...(options.secret === true ? { secret: true } : {}),
+    ...extra,
+  });
+}
+
+function validatePlainObject(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  const prototype = value && typeof value === 'object' ? Object.getPrototypeOf(value) : null;
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || (prototype !== Object.prototype && prototype !== null)) {
+    validationError(value, options, {
+      code: 'invalid-object',
+      expectation: 'must be a plain object',
+      expected: 'plain object',
+    });
+  }
+  return value;
+}
+
+function validateString(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  if (typeof value !== 'string') {
+    validationError(value, options, {
+      code: 'invalid-string',
+      expectation: 'must be a string',
+      expected: 'string',
+    });
+  }
+  const normalized = options.trim === true ? value.trim() : value;
+  const minLength = Number.isInteger(options.minLength) && options.minLength >= 0
+    ? options.minLength
+    : (options.allowEmpty === false ? 1 : null);
+  const maxLength = Number.isInteger(options.maxLength) && options.maxLength >= 0
+    ? options.maxLength
+    : null;
+  if ((minLength !== null && normalized.length < minLength)
+      || (maxLength !== null && normalized.length > maxLength)) {
+    validationError(value, options, {
+      code: 'invalid-string',
+      expectation: 'has an invalid length',
+      expected: 'string',
+    }, {
+      ...(minLength !== null ? { minLength } : {}),
+      ...(maxLength !== null ? { maxLength } : {}),
+    });
+  }
+  return normalized;
+}
+
+function validateBoolean(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  if (typeof value !== 'boolean') {
+    validationError(value, options, {
+      code: 'invalid-boolean',
+      expectation: 'must be a boolean',
+      expected: 'boolean',
+    });
+  }
+  return value;
+}
+
+function validateFiniteNumber(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    validationError(value, options, {
+      code: 'invalid-number',
+      expectation: 'must be a finite number',
+      expected: 'finite number',
+    });
+  }
+  return value;
+}
+
+function validateInteger(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
+    validationError(value, options, {
+      code: 'invalid-integer',
+      expectation: 'must be an integer',
+      expected: 'integer',
+    });
+  }
+  return value;
+}
+
+function validateArray(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  if (!Array.isArray(value)) {
+    validationError(value, options, {
+      code: 'invalid-array',
+      expectation: 'must be an array',
+      expected: 'array',
+    });
+  }
+  const minLength = Number.isInteger(options.minLength) && options.minLength >= 0
+    ? options.minLength
+    : null;
+  const maxLength = Number.isInteger(options.maxLength) && options.maxLength >= 0
+    ? options.maxLength
+    : null;
+  if ((minLength !== null && value.length < minLength)
+      || (maxLength !== null && value.length > maxLength)) {
+    validationError(value, options, {
+      code: 'invalid-array',
+      expectation: 'has an invalid length',
+      expected: 'array',
+    }, {
+      ...(minLength !== null ? { minLength } : {}),
+      ...(maxLength !== null ? { maxLength } : {}),
+    });
+  }
+  if (typeof options.itemValidator === 'function') {
+    value.forEach((entry, index) => {
+      options.itemValidator(entry, {
+        index,
+        path: [...(Array.isArray(options.path) ? options.path : [options.path || options.field || 'value']), index],
+      });
+    });
+  }
+  return value;
+}
+
+function validateEnum(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  if (!Array.isArray(options.values) || options.values.length === 0) {
+    throw new TypeError('validateEnum requires a non-empty values array');
+  }
+  if (!options.values.some(candidate => Object.is(candidate, value))) {
+    validationError(value, options, {
+      code: 'invalid-enum',
+      expectation: 'must be one of the allowed values',
+      expected: 'enum',
+    }, { allowedValues: options.values });
+  }
+  return value;
+}
+
+function validateRange(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    validationError(value, options, {
+      code: 'invalid-number',
+      expectation: 'must be a finite number',
+      expected: 'finite number',
+    });
+  }
+  const hasMin = Number.isFinite(options.min);
+  const hasMax = Number.isFinite(options.max);
+  if (!hasMin && !hasMax) throw new TypeError('validateRange requires a finite min or max');
+  const inclusiveMin = options.inclusiveMin !== false;
+  const inclusiveMax = options.inclusiveMax !== false;
+  const below = hasMin && (inclusiveMin ? value < options.min : value <= options.min);
+  const above = hasMax && (inclusiveMax ? value > options.max : value >= options.max);
+  if (below || above) {
+    validationError(value, options, {
+      code: 'out-of-range',
+      expectation: 'is outside the allowed range',
+      expected: 'number in range',
+    }, {
+      ...(hasMin ? { min: options.min, inclusiveMin } : {}),
+      ...(hasMax ? { max: options.max, inclusiveMax } : {}),
+    });
+  }
+  return value;
+}
+
+function validateIdentifier(value, options = {}) {
+  if (optionalValue(value, options)) return value;
+  if (typeof value !== 'string') {
+    validationError(value, options, {
+      code: 'invalid-identifier',
+      expectation: 'must be a valid identifier',
+      expected: 'identifier',
+    });
+  }
+  const normalized = options.trim === true ? value.trim() : value;
+  const maxLength = Number.isInteger(options.maxLength) && options.maxLength > 0
+    ? options.maxLength
+    : DEFAULT_IDENTIFIER_MAX;
+  const pattern = options.pattern instanceof RegExp ? options.pattern : DEFAULT_IDENTIFIER_RE;
+  pattern.lastIndex = 0;
+  const validPattern = pattern.test(normalized);
+  pattern.lastIndex = 0;
+  if (!normalized || normalized.length > maxLength || !validPattern) {
+    validationError(value, options, {
+      code: 'invalid-identifier',
+      expectation: 'must be a valid identifier',
+      expected: 'identifier',
+    }, { minLength: 1, maxLength });
+  }
+  return normalized;
+}
+
+module.exports = {
+  API_INPUT_ERROR_DETAILS_MAX,
+  ApiInputError,
+  buildApiErrorEnvelope,
+  toApiErrorResponse,
+  summarizeRejectedValue,
+  isApiInputError,
+  validatePlainObject,
+  validateString,
+  validateBoolean,
+  validateFiniteNumber,
+  validateInteger,
+  validateArray,
+  validateEnum,
+  validateRange,
+  validateIdentifier,
+};