@carecard/validate 3.38.0 → 3.39.0

package/.agents/skills/pkg-validate-validation-library/SKILL.md

@@ -130,6 +130,16 @@ depend on those folders being present.
   such as `:reviewed:`. Do not use reaction-token syntax to relax human text.
 - General low-level validators should be deterministic predicate functions that
   return `true` or `false`.
+- Use the direct field-specific predicates from `lib/inputValidation.js` only
+  for the matching contract. Keep existing stricter character rules and
+  source-owned lengths, requiredness and nullability. Validate raw input before
+  trimming; multiline fields may accept LF and CRLF, never standalone CR.
+- Use `isHttpUrlString`, `isMimeTypeString`, `isIdempotencyKeyString` and
+  `isNonNegativeSafeInteger` at their structured boundaries. Do not parse a
+  numeric prefix or rely on a URL parser to discard unsafe raw characters.
+- Keep extensible metadata as safe JSON data through `isSafeJsonValue` or
+  `isSafeJsonString`. Reconstructed and flattened whitelist properties must be
+  own data, including reserved-looking keys; never follow inherited paths.
 - `isEmailString` is the sole CareCard email-format decision. It accepts an
   unmodified ASCII address no longer than 254 characters, with one practical
   dot-atom local part no longer than 64 characters and a valid multi-label

package/index.d.ts

@@ -8,6 +8,27 @@ export type ValidatePropertiesResult = Record<string, unknown>;
 export type BoolValidator = (input: unknown) => boolean;
 export type InStringArrayValidator = (stringArray: readonly string[], input: unknown) => boolean;
 
+/** Checks raw and NFKC single-line human text characters; callers own lengths and requiredness. */
+export const isSingleLineTextString: BoolValidator;
+/** Checks the human text character allowlist with LF or CRLF line endings. */
+export const isMultilineTextString: BoolValidator;
+/** Checks an unmodified HTTP(S) URL without whitespace, controls, backslashes or angle brackets. */
+export const isHttpUrlString: BoolValidator;
+/** Checks a concrete MIME type and optional token/quoted parameters. */
+export const isMimeTypeString: BoolValidator;
+/** Checks an ASCII idempotency key of 1 through 128 code units. */
+export const isIdempotencyKeyString: BoolValidator;
+/** Checks a nonnegative safe integer number or complete decimal integer string. */
+export const isNonNegativeSafeInteger: BoolValidator;
+/** Checks a version-four UUID with an RFC variant. */
+export const isValidUuidV4String: BoolValidator;
+/** Checks an extensible JSON object/array and nested text, with a 10000-code-unit serialized budget. */
+export const isSafeJsonValue: BoolValidator;
+/** Checks serialized JSON metadata without altering its representation or original length budget. */
+export const isSafeJsonString: BoolValidator;
+/** Checks single-line documentation search text, including printable code punctuation. */
+export const isDocumentationSearchString: BoolValidator;
+
 export type PasswordValidationFailureReason =
   'invalid_type' | 'invalid_unicode' | 'too_short' | 'too_long' | 'blocked';
 export type PasswordValidationResult =

package/index.js

@@ -3,6 +3,7 @@ const { validatePassword, ...legacyValidate } = validate;
 const validateProperties = require('./lib/validateProperties');
 const validateWhitelistProperties = require('./lib/validateWhitelistProperties');
 const validateNewUserRoleRequest = require('./lib/validateNewUserRoleRequest');
+const inputValidation = require('./lib/inputValidation');
 
 module.exports = {
   validate: legacyValidate,
@@ -12,4 +13,5 @@ module.exports = {
   ...validateNewUserRoleRequest,
   ...legacyValidate,
   ...validateProperties,
+  ...inputValidation,
 };

package/lib/inputValidation.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const { isValidIntegerString, isValidJsonString } = require('./validate');
+
+const SINGLE_LINE_TEXT =
+  /^[\p{L}\p{M}\p{N}\p{Zs}\p{Pd}\p{Sc}\p{Extended_Pictographic}\p{Emoji_Presentation}\p{Emoji_Modifier}_.,'’‘“”"():;!?/@&#+%=[\]{}*\u200c\u200d]*$/u;
+const DOCUMENTATION_SEARCH =
+  /^[\x20-\x3b\x3d\x3f-\x7e\p{L}\p{M}\p{N}\p{Zs}\p{Pd}\p{Sc}\p{Extended_Pictographic}\p{Emoji_Presentation}\p{Emoji_Modifier}\u200c\u200d]*$/u;
+const HTTP_URL_CHARACTERS =
+  /^[-\p{L}\p{M}\p{N}\p{Pd}\p{Sc}\p{Extended_Pictographic}\p{Emoji_Presentation}\p{Emoji_Modifier}._~:/?#[\]@!$&'()*+,;=%\u200c\u200d]+$/u;
+const MIME_NAME = '[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}';
+const MIME_TOKEN = "[!#$%&'*+.^_`|~0-9A-Za-z-]+";
+const MIME_QUOTED_VALUE =
+  '"(?:[\\x20\\x21\\x23-\\x3b\\x3d\\x3f-\\x5b\\x5d-\\x7e]|\\\\[\\x20-\\x3b\\x3d\\x3f-\\x7e])*"';
+const MIME_TYPE = new RegExp(
+  `^${MIME_NAME}/${MIME_NAME}(?: *; *${MIME_NAME}=(?:${MIME_TOKEN}|${MIME_QUOTED_VALUE}))*$`,
+);
+
+function hasRawAndNormalizedCharacters(value, allowlist) {
+  if (typeof value !== 'string' || !value.isWellFormed()) {
+    return false;
+  }
+  const rawCharacters = value.replace(
+    /[\u2024-\u2026\u207d\u207e\u208d\u208e\ufe10-\ufe19\ufe30-\ufe36\ufe4d-\ufe52\ufe54-\ufe5e\ufe60-\ufe61\ufe68-\ufe6b\uff01-\uff02\uff03-\uff0b\uff0c-\uff0f\uff1a-\uff1b\uff1d\uff1f-\uff20\uff3b\uff3d\uff3f\uff5b\uff5d]/gu,
+    '',
+  );
+  return allowlist.test(rawCharacters) && allowlist.test(value.normalize('NFKC'));
+}
+
+/** Character validation only; the owning field defines length and requiredness. */
+function isSingleLineTextString(value) {
+  return hasRawAndNormalizedCharacters(value, SINGLE_LINE_TEXT);
+}
+
+/** Allows LF and CRLF line endings, while rejecting standalone CR. */
+function isMultilineTextString(value) {
+  return (
+    typeof value === 'string' &&
+    value.isWellFormed() &&
+    isSingleLineTextString(value.replace(/\r\n/g, '\n').replace(/\n/g, ''))
+  );
+}
+
+function isDocumentationSearchString(value) {
+  return hasRawAndNormalizedCharacters(value, DOCUMENTATION_SEARCH);
+}
+
+function isHttpUrlString(value) {
+  if (!hasRawAndNormalizedCharacters(value, HTTP_URL_CHARACTERS)) {
+    return false;
+  }
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' || url.protocol === 'http:';
+  } catch {
+    return false;
+  }
+}
+
+function isMimeTypeString(value) {
+  return (
+    typeof value === 'string' && /^[\x20-\x3b\x3d\x3f-\x7e]+$/.test(value) && MIME_TYPE.test(value)
+  );
+}
+
+function isIdempotencyKeyString(value) {
+  return typeof value === 'string' && value.length <= 128 && /^[A-Za-z0-9_.:-]+$/.test(value);
+}
+
+function isNonNegativeSafeInteger(value) {
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && value >= 0;
+  }
+  return isValidIntegerString(value) && Number.isSafeInteger(Number(value));
+}
+
+function isValidUuidV4String(value) {
+  return (
+    typeof value === 'string' &&
+    value.length === 36 &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+  );
+}
+
+function isJsonContainer(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    (Array.isArray(value) ||
+      Object.getPrototypeOf(value) === Object.prototype ||
+      Object.getPrototypeOf(value) === null)
+  );
+}
+
+function isSafeJsonScalar(value) {
+  return (
+    value === null ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' && Number.isFinite(value)) ||
+    (typeof value === 'string' && isMultilineTextString(value))
+  );
+}
+
+function appendSafeJsonProperties(value, pending) {
+  for (const [key, property] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+    if (!property.enumerable) {
+      continue;
+    }
+    if (!isSingleLineTextString(key) || !Object.hasOwn(property, 'value')) {
+      return false;
+    }
+    pending.push({ value: property.value, finished: false });
+  }
+  return Object.getOwnPropertySymbols(value).length === 0;
+}
+
+function hasSafeJsonTree(root) {
+  const ancestors = new Set();
+  const pending = [{ value: root, finished: false }];
+  while (pending.length > 0) {
+    const { value, finished } = pending.pop();
+    if (finished) {
+      ancestors.delete(value);
+    } else if (!isSafeJsonScalar(value)) {
+      if (!isJsonContainer(value) || ancestors.has(value)) {
+        return false;
+      }
+      ancestors.add(value);
+      pending.push({ value, finished: true });
+      if (!appendSafeJsonProperties(value, pending)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+/** Extensible JSON object/array, with the existing 10000-code-unit metadata budget. */
+function isSafeJsonValue(value) {
+  try {
+    return (
+      isJsonContainer(value) && hasSafeJsonTree(value) && JSON.stringify(value).length <= 10000
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isSafeJsonString(value) {
+  return isValidJsonString(value) && isSafeJsonValue(JSON.parse(value));
+}
+
+module.exports = {
+  isSingleLineTextString,
+  isMultilineTextString,
+  isHttpUrlString,
+  isMimeTypeString,
+  isIdempotencyKeyString,
+  isNonNegativeSafeInteger,
+  isValidUuidV4String,
+  isSafeJsonValue,
+  isSafeJsonString,
+  isDocumentationSearchString,
+};

package/lib/validateProperties.js

@@ -11,7 +11,6 @@ const {
   isFileNameString,
   isCharactersString,
   isValidIntegerString,
-  isValidJsonString,
   isImageUrl,
   isValidDomainName,
   isValidTimestampzString,
@@ -26,6 +25,12 @@ const {
   isUserRoleRequestRoleString,
   isCountryCodeString,
 } = require('./validate');
+const {
+  isSingleLineTextString,
+  isHttpUrlString,
+  isSafeJsonValue,
+  isSafeJsonString,
+} = require('./inputValidation');
 
 // Pattern: Boundary Validation - preserves field-specific formats while omitting invalid properties.
 function validateProperties(obj = {}) {
@@ -101,7 +106,7 @@ function validateProperties(obj = {}) {
         }
         break;
       case 'street':
-        if (isStreetString(value)) {
+        if (isStreetString(value) && isSingleLineTextString(value)) {
           returnObj[key] = value;
         }
         break;
@@ -271,7 +276,7 @@ function validateProperties(obj = {}) {
         }
         break;
       case 'about':
-        if (isValidJsonString(value)) {
+        if (isSafeJsonString(value)) {
           returnObj[key] = value;
         }
         break;
@@ -283,7 +288,7 @@ function validateProperties(obj = {}) {
       case 'meta_data':
       case 'metaData':
       case 'metadata':
-        if (isValidJsonString(JSON.stringify(value))) {
+        if (isSafeJsonValue(value)) {
           returnObj[key] = value;
         }
         break;
@@ -297,7 +302,7 @@ function validateProperties(obj = {}) {
       case 'website':
       case 'file_url':
       case 'fileUrl':
-        if (isImageUrl(value) || isValidUrl(value)) {
+        if (isImageUrl(value) || (isValidUrl(value) && isHttpUrlString(value))) {
           returnObj[key] = value;
         }
         break;

package/lib/validateWhitelistProperties.js

@@ -142,16 +142,25 @@ function readLeaf(obj, segments) {
  * @param {string[]} segments
  * @param {*} value
  */
+function defineWhitelistDataProperty(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  });
+}
+
 function writeLeaf(target, segments, value) {
   let current = target;
   for (let i = 0; i < segments.length - 1; i++) {
     const key = segments[i];
-    if (current[key] === null || typeof current[key] !== 'object') {
-      current[key] = {};
+    if (!Object.hasOwn(current, key) || current[key] === null || typeof current[key] !== 'object') {
+      defineWhitelistDataProperty(current, key, {});
     }
     current = current[key];
   }
-  current[segments[segments.length - 1]] = value;
+  defineWhitelistDataProperty(current, segments[segments.length - 1], value);
 }
 
 /**
@@ -176,7 +185,7 @@ function flattenObject(obj, prefix = '', out = {}) {
     ) {
       flattenObject(value, path, out);
     } else {
-      out[path] = value;
+      defineWhitelistDataProperty(out, path, value);
     }
   }
   return out;
@@ -208,8 +217,8 @@ function flattenObjectByLeafKey(obj, out = {}, depthByKey = {}, depth = 1) {
       flattenObjectByLeafKey(value, out, depthByKey, depth + 1);
     } else {
       if (!Object.prototype.hasOwnProperty.call(out, key) || depth < depthByKey[key]) {
-        out[key] = value;
-        depthByKey[key] = depth;
+        defineWhitelistDataProperty(out, key, value);
+        defineWhitelistDataProperty(depthByKey, key, depth);
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carecard/validate",
-  "version": "3.38.0",
+  "version": "3.39.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/CareCard-ca/pkg-validate.git"
@@ -47,7 +47,7 @@
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@carecard/common-util": "3.38.0"
+    "@carecard/common-util": "3.39.0"
   },
   "nyc": {
     "all": true,

package/readme.md

@@ -64,9 +64,9 @@ const {
 } = require('@carecard/validate');
 ```
 
-General validators are available both as top-level exports and under the
-deprecated `validate` namespace. `validatePassword` is intentionally available
-only as one direct export.
+The original validators are available both as top-level exports and under the
+deprecated `validate` namespace. New field-specific validators and
+`validatePassword` use direct exports.
 
 The package root is safe to import from browser bundles. Its whitelist and role
 request validators use the focused `@carecard/common-util/case-converter` and
@@ -140,6 +140,46 @@ Passwords, emails, URLs, JSON, addresses, phones and reaction tokens keep their
 format contracts. This allowlist does not replace output encoding, parameterized
 queries, upload-content validation, or storage-path generation.
 
+### Field-specific input characters
+
+Use `isSingleLineTextString` for previously unrestricted human text and
+`isMultilineTextString` for comments that support line breaks. They check raw
+and NFKC-normalized characters before any trimming. They allow Unicode letters,
+marks, numbers, spaces, dashes, currency symbols, emoji and script/emoji joiners,
+plus `_ . , ' ’ ‘ “ ” " ( ) : ; ! ? / @ & # + % = [ ] { } *` and their
+explicitly supported compatibility forms. Both reject angle brackets,
+malformed Unicode, private-use characters, control and unwanted format
+characters. Multiline text permits LF and CRLF; standalone CR is rejected.
+Empty strings and ordinary spaces pass the lexical check so the owning field
+can retain its requiredness, nullability and length contract. Do not replace an
+existing stricter character rule with these predicates.
+
+`isHttpUrlString` checks an unmodified HTTP(S) URL, including its raw
+characters. It rejects whitespace, controls, backslashes and angle brackets
+instead of allowing a URL parser to discard or escape them. Keep the owning
+field's existing length limit. `isMimeTypeString` checks concrete registered
+type/subtype syntax and optional token or quoted parameters; see
+[RFC 6838](https://www.rfc-editor.org/rfc/rfc6838.html#section-4.2) and
+[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-8.3.1).
+
+`isIdempotencyKeyString` permits only ASCII letters, digits, `_ . : -`, at most
+128 code units. `isNonNegativeSafeInteger` accepts a safe integer number or a
+complete decimal integer string, with no signs, suffixes, hexadecimal or
+scientific notation. `isValidUuidV4String` retains version-four identifiers
+where the service contract requires them. `isDocumentationSearchString`
+permits single-line documentation queries with printable code punctuation,
+excluding angle brackets and unsafe Unicode/control characters.
+
+`isSafeJsonValue` preserves extensible JSON object/array metadata, including
+reserved-looking keys as data. It validates nested keys as single-line text,
+string values as multiline text, finite numbers, booleans, nulls, objects and
+arrays. It rejects cycles and values that JSON would silently discard, and
+retains the 10000-code-unit serialized budget. `isSafeJsonString` checks the
+same contract in an existing serialized JSON field without rewriting it.
+Whitelist output creates own data properties at every path and during
+flattening. Existing property rules additionally require raw single-line
+streets, safe HTTP(S) URL characters and safe nested JSON.
+
 ## `validateProperties(obj)`
 
 `validateProperties` accepts an object and returns a new object that contains