@contrast/assess 1.78.0 → 1.79.0

package/lib/dataflow/propagation/install/zod/matrix.js

@@ -0,0 +1,149 @@
+/*
+ * Copyright: 2026 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+
+'use strict';
+
+const {
+  DataflowTag: { STRING_TYPE_CHECKED, ALPHANUM_SPACE_HYPHEN, LIMITED_CHARS, CUSTOM_VALIDATED },
+} = require('@contrast/common');
+
+// check-kind names that zod v3 (a flat `check.kind` string) and zod v4 (a
+// `check._zod.def.format` string, when `check._zod.def.check ===
+// 'string_format'`) happen to spell identically, with the same tag - shared
+// so neither version's table has to repeat these entries. Anything either
+// version names or tags differently lives in that version's own table below
+// instead of being forced into this shared shape.
+const COMMON_CHECK_MATRIX = {
+  includes: STRING_TYPE_CHECKED,
+  url: STRING_TYPE_CHECKED,
+  emoji: STRING_TYPE_CHECKED,
+
+  uuid: ALPHANUM_SPACE_HYPHEN,
+  cuid: ALPHANUM_SPACE_HYPHEN,
+  cuid2: ALPHANUM_SPACE_HYPHEN,
+  ulid: ALPHANUM_SPACE_HYPHEN,
+  nanoid: ALPHANUM_SPACE_HYPHEN,
+  jwt: ALPHANUM_SPACE_HYPHEN,
+  base64: ALPHANUM_SPACE_HYPHEN,
+  base64url: ALPHANUM_SPACE_HYPHEN,
+
+  email: LIMITED_CHARS,
+  date: LIMITED_CHARS,
+  datetime: LIMITED_CHARS,
+  time: LIMITED_CHARS,
+  duration: LIMITED_CHARS,
+
+  regex: CUSTOM_VALIDATED,
+};
+
+const v3 = {
+  // zod v3's checks are a flat array on ZodString's own def (`_def.checks`),
+  // each a plain `{kind: '...', ...}` object - no nested format/check split
+  // like v4's `_zod.def.check`/`format`, so one flat table keyed by
+  // `check.kind` covers every string check. `nonempty` is deliberately
+  // absent - `ZodString.nonempty()` compiles to `.min(1)`, there's no
+  // distinct 'nonempty' check kind to key off of.
+  CHECK_KIND_MATRIX: {
+    ...COMMON_CHECK_MATRIX,
+    min: STRING_TYPE_CHECKED,
+    max: STRING_TYPE_CHECKED,
+    length: STRING_TYPE_CHECKED,
+    startsWith: STRING_TYPE_CHECKED,
+    endsWith: STRING_TYPE_CHECKED,
+
+    ip: LIMITED_CHARS,
+    cidr: LIMITED_CHARS,
+  },
+
+  // check.kind values that mutate the string in place (produce a NEW string
+  // identity inside zod) rather than just validating it - handled by the
+  // retrack path in process-result-v3.js, not tagged via the matrix above.
+  // v3 has no validating `lowercase`/`uppercase` checks like v4 - only these
+  // mutating ones.
+  OVERWRITE_CHECK_KINDS: new Set(['trim', 'toLowerCase', 'toUpperCase']),
+
+  // schema._def.typeName values whose successful validation should untrack
+  // the value entirely, rather than tag it - it's now constrained to a fixed
+  // allow-list of values. Unlike v4 (which collapses nativeEnum into 'enum'),
+  // v3 keeps ZodNativeEnum as a distinct typeName.
+  UNTRACKING_SCHEMA_TYPES: new Set(['ZodEnum', 'ZodNativeEnum', 'ZodLiteral']),
+};
+
+const v4 = {
+  // `.email()`, `.uuid()`, `.url()`, `.ipv4()`, etc. all share the same underlying
+  // check class ($ZodCheckStringFormat) and are only discriminated by
+  // `check._zod.def.format`, not by `check._zod.def.check` (which is the fixed
+  // string 'string_format' for all of them). `.includes()`/`.startsWith()`/
+  // `.endsWith()`/`.regex()`/`.lowercase()`/`.uppercase()` are format checks too.
+  //
+  // keyed by check._zod.def.format, when check._zod.def.check === 'string_format'
+  FORMAT_MATRIX: {
+    ...COMMON_CHECK_MATRIX,
+    ends_with: STRING_TYPE_CHECKED,
+    lowercase: STRING_TYPE_CHECKED,
+    starts_with: STRING_TYPE_CHECKED,
+    uppercase: STRING_TYPE_CHECKED,
+
+    guid: ALPHANUM_SPACE_HYPHEN,
+    hex: ALPHANUM_SPACE_HYPHEN,
+    ksuid: ALPHANUM_SPACE_HYPHEN,
+    xid: ALPHANUM_SPACE_HYPHEN,
+
+    // hash("<algorithm>")
+    md5_hex: ALPHANUM_SPACE_HYPHEN,
+    md5_base64: ALPHANUM_SPACE_HYPHEN,
+    md5_base64url: ALPHANUM_SPACE_HYPHEN,
+    sha1_hex: ALPHANUM_SPACE_HYPHEN,
+    sha1_base64: ALPHANUM_SPACE_HYPHEN,
+    sha1_base64url: ALPHANUM_SPACE_HYPHEN,
+    sha256_hex: ALPHANUM_SPACE_HYPHEN,
+    sha256_base64: ALPHANUM_SPACE_HYPHEN,
+    sha256_base64url: ALPHANUM_SPACE_HYPHEN,
+    sha384_hex: ALPHANUM_SPACE_HYPHEN,
+    sha384_base64: ALPHANUM_SPACE_HYPHEN,
+    sha384_base64url: ALPHANUM_SPACE_HYPHEN,
+    sha512_hex: ALPHANUM_SPACE_HYPHEN,
+    sha512_base64: ALPHANUM_SPACE_HYPHEN,
+    sha512_base64url: ALPHANUM_SPACE_HYPHEN,
+
+    cidrv4: LIMITED_CHARS,
+    cidrv6: LIMITED_CHARS,
+    e164: LIMITED_CHARS,
+    ipv4: LIMITED_CHARS,
+    ipv6: LIMITED_CHARS,
+    mac: LIMITED_CHARS,
+  },
+
+  // keyed by check._zod.def.check, when check !== 'string_format'. Plain
+  // .min()/.max()/.length() get their own distinct check identifiers.
+  // 'overwrite' (.trim()/.toLowerCase()/.toUpperCase()/.normalize()/.slugify())
+  // and 'custom' (refine/superRefine/check(fn)) are deliberately absent here -
+  // 'overwrite' is handled by the retrack path and 'custom' by the
+  // trust_custom_validators-gated path in process-result-v4.js, neither is
+  // tagged via this ungated matrix.
+  CHECK_TYPE_MATRIX: {
+    min_length: STRING_TYPE_CHECKED,
+    max_length: STRING_TYPE_CHECKED,
+    length_equals: STRING_TYPE_CHECKED,
+  },
+
+  // schema._zod.def.type values whose successful validation should untrack the
+  // value entirely, rather than tag it - it's now constrained to a fixed
+  // allow-list of values. zod v4 has no separate 'nativeEnum' schema type;
+  // z.nativeEnum() compiles to the same 'enum' type.
+  UNTRACKING_SCHEMA_TYPES: new Set(['enum', 'literal']),
+};
+
+module.exports = { v3, v4 };

package/lib/dataflow/propagation/install/zod/process-result-v3.js

@@ -0,0 +1,228 @@
+/*
+ * Copyright: 2026 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+
+'use strict';
+
+const {
+  DataflowTag: { STRING_TYPE_CHECKED },
+  isNonEmptyObject,
+} = require('@contrast/common');
+const { CHECK_KIND_MATRIX, OVERWRITE_CHECK_KINDS, UNTRACKING_SCHEMA_TYPES } = require('./matrix').v3;
+
+// schema._def.typeName values that pass the value through to `_def.innerType`
+// completely unchanged - safe to unwrap transparently when looking for the
+// concrete leaf schema that actually carries checks. ZodBranded is NOT here -
+// it uses `_def.type` instead of `_def.innerType` for its wrapped schema.
+const INNER_TYPE_WRAPPERS = new Set(['ZodOptional', 'ZodNullable', 'ZodDefault', 'ZodCatch', 'ZodReadonly']);
+const TYPE_KEY_WRAPPERS = new Set(['ZodBranded']);
+// backstop against a self-referential `z.lazy(() => schema)` spinning forever
+const MAX_UNWRAP_DEPTH = 100;
+
+module.exports = function(core) {
+  const { logger } = core;
+  const {
+    applyTags,
+    untrackValue,
+    retrackOverwrite,
+    tagCustomValidated,
+    handleTransformLike,
+    hasAnyTrackedValue,
+    getPropagatorContext,
+  } = require('./utils')(core);
+
+  /**
+   * Unwraps wrapper schema types (optional/nullable/default/branded/lazy/...)
+   * to find the schema that actually carries checks. `.catch()` is included
+   * here: on the SUCCESS path (the only path this instrumentation ever sees,
+   * since the parse-family hooks only fire on success), a `.catch()`
+   * schema's result is either the inner schema's own validated value, or a
+   * fallback substituted by user code - in the fallback case
+   * `tracker.getData(result)` naturally finds nothing tracked (a fresh
+   * literal), so no special-casing is needed.
+   */
+  function resolveConcreteSchema(schema) {
+    let current = schema;
+    for (let depth = 0; depth < MAX_UNWRAP_DEPTH && current?._def; depth++) {
+      const { typeName } = current._def;
+      if (INNER_TYPE_WRAPPERS.has(typeName)) {
+        current = current._def.innerType;
+        continue;
+      }
+      if (TYPE_KEY_WRAPPERS.has(typeName)) {
+        current = current._def.type;
+        continue;
+      }
+      if (typeName === 'ZodLazy') {
+        current = current._def.getter();
+        continue;
+      }
+      return current;
+    }
+    return current;
+  }
+
+  /**
+   * Collects every DataflowTag that applies to a concrete (already-unwrapped)
+   * schema node. String-family schemas always get a baseline
+   * STRING_TYPE_CHECKED (mirroring joi's string.validate() tagging every
+   * successfully validated string, regardless of additional rules), on top
+   * of whichever more specific tags its chained checks add. Unlike v4, v3
+   * has no per-node format schema (no top-level `z.email()`), so every check
+   * is an entry in `def.checks`, never the node's own def.
+   */
+  function checksToTags(def) {
+    const tags = new Set();
+    if (def.typeName === 'ZodString') tags.add(STRING_TYPE_CHECKED);
+
+    for (const check of def.checks ?? []) {
+      const tag = CHECK_KIND_MATRIX[check.kind];
+      if (tag) tags.add(tag);
+    }
+
+    return tags;
+  }
+
+  function hasOverwriteCheck(def) {
+    return (def.checks ?? []).some((check) => OVERWRITE_CHECK_KINDS.has(check.kind));
+  }
+
+  /**
+   * Writes a walked value back into its container, guarding against
+   * `.readonly()` schemas: zod freezes the object/array on the success path
+   * (`Object.freeze`), so writing back into it throws in strict mode. Skip
+   * the write when nothing changed (the common case) or when the container
+   * is frozen - in the frozen case, retracking (e.g. a nested `.trim()`)
+   * can't be reflected in the output, which is an accepted degradation.
+   */
+  function assignWalked(container, key, walked) {
+    if (container[key] === walked) return;
+    if (Object.isFrozen(container)) return;
+    container[key] = walked;
+  }
+
+  /**
+   * Handles a ZodEffects node - the schema shape `.refine()`, `.superRefine()`,
+   * `.transform()`, and `.preprocess()` all compile to.
+   *
+   * Unlike v4 (where `.refine()`/`.superRefine()` append a 'custom' check
+   * onto the SAME schema node), v3's `.refine()`/`.superRefine()` return a
+   * NEW ZodEffects WRAPPING the original schema (`def.schema`). A naive port
+   * that only gated CUSTOM_VALIDATED on this node would silently drop
+   * STRING_TYPE_CHECKED/format tags and any retracking for every
+   * `.refine()`/`.superRefine()` call - so the inner schema is walked FIRST,
+   * and CUSTOM_VALIDATED is layered on top of whatever that walk produced.
+   * The refinement function's return value is ignored by zod itself, so
+   * `result` here is exactly whatever the inner schema's own parse produced.
+   *
+   * `.preprocess()` is out of v1 scope: the pre-preprocess value is a
+   * different, unobservable input than what we receive here.
+   */
+  function handleEffects(concrete, def, input, result, path) {
+    if (def.effect.type === 'refinement') {
+      const walked = walk(def.schema, input, result, path);
+      return tagCustomValidated({
+        sourceValue: walked,
+        targetValue: walked,
+        schema: concrete,
+        methodName: 'refine',
+        retrack: false,
+      });
+    }
+
+    if (def.effect.type === 'transform') {
+      return handleTransformLike(def.schema, input, result);
+    }
+
+    return result;
+  }
+
+  /**
+   * Recursively walks a schema alongside its pre-parse input and post-parse
+   * result, tagging/untracking/retracking tracked strings it finds. Returns
+   * the (possibly retracked) result value - the caller must use this return
+   * value, since retracking (trim/toLowerCase/transform) produces a NEW
+   * string object that the original caller of `.parse()` needs to actually
+   * receive in order for the tag to travel with it.
+   */
+  function walk(schema, input, result, path) {
+    const concrete = resolveConcreteSchema(schema);
+    if (!concrete?._def) return result;
+    const def = concrete._def;
+
+    if (UNTRACKING_SCHEMA_TYPES.has(def.typeName)) {
+      untrackValue(result);
+      return result;
+    }
+
+    if (def.typeName === 'ZodEffects') {
+      return handleEffects(concrete, def, input, result, path);
+    }
+
+    if (def.typeName === 'ZodPipeline') {
+      return handleTransformLike(def.in, input, result);
+    }
+
+    if (typeof result === 'string') {
+      let taggedResult = result;
+      if (hasOverwriteCheck(def)) {
+        taggedResult = retrackOverwrite(input, result, concrete);
+      }
+      applyTags(taggedResult, checksToTags(def), concrete, 'string');
+      return taggedResult;
+    }
+
+    switch (def.typeName) {
+      case 'ZodObject':
+        if (isNonEmptyObject(input) && isNonEmptyObject(result)) {
+          for (const key of Object.keys(concrete.shape)) {
+            assignWalked(result, key, walk(concrete.shape[key], input[key], result[key], [...path, key]));
+          }
+        }
+        return result;
+      case 'ZodArray':
+        if (Array.isArray(result)) {
+          result.forEach((value, i) => {
+            assignWalked(result, i, walk(concrete.element, input?.[i], value, [...path, i]));
+          });
+        }
+        return result;
+      default:
+        // unions/discriminatedUnion/intersection/tuples/records/maps/sets/
+        // promises/functions are deliberately out of v1 scope, mirroring v4.
+        return result;
+    }
+  }
+
+  /**
+   * Entry point called from the safeParse-family post-hook. Bails out
+   * cheaply unless something in `input` or `result` is actually tracked,
+   * mirroring joi's early-return checks. Returns the (possibly retracked)
+   * result - callers must use the return value as the definitive result
+   * going forward.
+   */
+  function handleParseSuccess(schema, input, result) {
+    try {
+      if (!getPropagatorContext()) return result;
+      if (!hasAnyTrackedValue(input) && !hasAnyTrackedValue(result)) return result;
+
+      return walk(schema, input, result, []);
+    } catch (err) {
+      logger.error({ err }, 'zod v3 parse propagation walk failed');
+      return result;
+    }
+  }
+
+  return { handleParseSuccess };
+};

package/lib/dataflow/propagation/install/zod/process-result-v4.js

@@ -0,0 +1,191 @@
+/*
+ * Copyright: 2026 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+
+'use strict';
+
+const {
+  DataflowTag: { STRING_TYPE_CHECKED },
+  isNonEmptyObject,
+} = require('@contrast/common');
+const { CHECK_TYPE_MATRIX, FORMAT_MATRIX, UNTRACKING_SCHEMA_TYPES } = require('./matrix').v4;
+
+// schema._zod.def.type values that pass the value through to `innerType`
+// completely unchanged - safe to unwrap transparently when looking for the
+// concrete leaf schema that actually carries checks.
+const TRANSPARENT_WRAPPER_TYPES = new Set([
+  'optional', 'exactOptional', 'nullable', 'default', 'prefault', 'nonoptional', 'success', 'readonly', 'catch',
+]);
+
+module.exports = function(core) {
+  const { logger } = core;
+  const {
+    applyTags,
+    untrackValue,
+    retrackOverwrite,
+    tagCustomValidated,
+    handleTransformLike,
+    hasAnyTrackedValue,
+    getPropagatorContext,
+  } = require('./utils')(core);
+
+  /**
+   * Unwraps wrapper schema types (optional/nullable/default/.../lazy) to find
+   * the schema that actually carries checks. `.catch()` is included here: on
+   * the SUCCESS path (the only path this instrumentation ever sees, since the
+   * parse-family hooks only fire on success), a `.catch()` schema's result is
+   * either the inner schema's own validated value, or a fallback substituted
+   * by user code - in the fallback case `tracker.getData(result)` naturally
+   * finds nothing tracked (a fresh literal), so no special-casing is needed.
+   */
+  function resolveConcreteSchema(schema) {
+    let current = schema;
+    while (current?._zod?.def) {
+      const { type, innerType } = current._zod.def;
+      if (TRANSPARENT_WRAPPER_TYPES.has(type)) {
+        current = innerType;
+        continue;
+      }
+      if (type === 'lazy') {
+        current = current._zod.innerType;
+        continue;
+      }
+      return current;
+    }
+    return current;
+  }
+
+  /**
+   * Resolves the DataflowTag for a single check-shaped def (either a schema's
+   * own def, when the schema itself is a format/check node e.g. z.email(), or
+   * an entry in some other schema's def.checks array, e.g. z.string().email()
+   * - both shapes carry the same {check, format} discriminator). Deliberately
+   * excludes 'overwrite' and 'custom' checks - both matrices omit those keys,
+   * since they're handled by dedicated, gated code paths below rather than
+   * this blanket lookup.
+   */
+  function tagForCheckDef(def) {
+    if (!def?.check) return null;
+    return def.check === 'string_format' ? FORMAT_MATRIX[def.format] : CHECK_TYPE_MATRIX[def.check];
+  }
+
+  /**
+   * Collects every DataflowTag that applies to a concrete (already-unwrapped)
+   * schema node. String-family schemas always get a baseline
+   * STRING_TYPE_CHECKED (mirroring joi's string.validate() tagging every
+   * successfully validated string, regardless of additional rules), on top
+   * of whichever more specific tags its own def or chained checks add.
+   */
+  function checksToTags(def) {
+    const tags = new Set();
+    if (def.type === 'string') tags.add(STRING_TYPE_CHECKED);
+
+    const ownTag = tagForCheckDef(def);
+    if (ownTag) tags.add(ownTag);
+
+    for (const check of def.checks ?? []) {
+      const tag = tagForCheckDef(check._zod?.def);
+      if (tag) tags.add(tag);
+    }
+
+    return tags;
+  }
+
+  function hasCheck(def, checkName) {
+    return (def.checks ?? []).some((check) => check._zod?.def?.check === checkName);
+  }
+
+  /**
+   * Recursively walks a schema alongside its pre-parse input and post-parse
+   * result, tagging/untracking/retracking tracked strings it finds. Returns
+   * the (possibly retracked) result value - the caller must use this return
+   * value, since retracking (trim/toLowerCase/transform) produces a NEW
+   * string object that the original caller of `.parse()` needs to actually
+   * receive in order for the tag to travel with it.
+   */
+  function walk(schema, input, result, path) {
+    const concrete = resolveConcreteSchema(schema);
+    if (!concrete?._zod?.def) return result;
+    const { def } = concrete._zod;
+
+    if (UNTRACKING_SCHEMA_TYPES.has(def.type)) {
+      untrackValue(result);
+      return result;
+    }
+
+    if (def.type === 'pipe') {
+      return handleTransformLike(def.in, input, result);
+    }
+
+    if (typeof result === 'string') {
+      let taggedResult = result;
+      if (hasCheck(def, 'overwrite')) {
+        taggedResult = retrackOverwrite(input, result, concrete);
+      }
+      applyTags(taggedResult, checksToTags(def), concrete, 'string');
+      if (hasCheck(def, 'custom')) {
+        taggedResult = tagCustomValidated({
+          sourceValue: input,
+          targetValue: taggedResult,
+          schema: concrete,
+          methodName: 'refine',
+          retrack: false,
+        });
+      }
+      return taggedResult;
+    }
+
+    switch (def.type) {
+      case 'object':
+        if (isNonEmptyObject(input) && isNonEmptyObject(result)) {
+          for (const key of Object.keys(def.shape)) {
+            result[key] = walk(def.shape[key], input[key], result[key], [...path, key]);
+          }
+        }
+        return result;
+      case 'array':
+        if (Array.isArray(result)) {
+          result.forEach((value, i) => {
+            result[i] = walk(def.element, input?.[i], value, [...path, i]);
+          });
+        }
+        return result;
+      default:
+        // unions/discriminatedUnion/xor/records/maps/sets/tuples/intersections
+        // are deliberately out of v1 scope - see plan's Open Questions.
+        return result;
+    }
+  }
+
+  /**
+   * Entry point called from the parse-family post-hook. Bails out cheaply
+   * unless something in `input` or `result` is actually tracked, mirroring
+   * joi's early-return checks. Returns the (possibly retracked) result -
+   * callers must use the return value as the definitive result going
+   * forward.
+   */
+  function handleParseSuccess(schema, input, result) {
+    try {
+      if (!getPropagatorContext()) return result;
+      if (!hasAnyTrackedValue(input) && !hasAnyTrackedValue(result)) return result;
+
+      return walk(schema, input, result, []);
+    } catch (err) {
+      logger.error({ err }, 'zod parse propagation walk failed');
+      return result;
+    }
+  }
+
+  return { handleParseSuccess };
+};