Add prototype-pollution guards and array key helpers (#565)

Add new public helpers for safe own-key iteration and unsafe target/key
detection, plus new array key utilities for dense and sparse array-like
values.

- add forEachOwnKeySafe(), isUnsafePropKey(), and isUnsafeTarget()
- update deep copy logic to use safe own-key iteration
- add arrKeys() iterator and arrIndexKeys() own-index enumeration
- export the new public APIs from the main index
- add tests covering sparse arrays, array-like values, and unsafe keys
- document the new security helpers in README and docs

Author: nev21

.size-limit.json

@@ -2,42 +2,42 @@
   {
     "name": "es5-full",
     "path": "lib/dist/es5/mod/ts-utils.js",
-    "limit": "29.5 kb",
+    "limit": "31 kb",
     "brotli": false,
     "running": false
   },
   {
     "name": "es6-full",
     "path": "lib/dist/es6/mod/ts-utils.js",
-    "limit": "28.5 kb",
+    "limit": "30 kb",
     "brotli": false,
     "running": false
   },
   {
     "name": "es5-full-brotli",
     "path": "lib/dist/es5/mod/ts-utils.js",
-    "limit": "10.5 kb",
+    "limit": "11 kb",
     "brotli": true,
     "running": false
   },
   {
     "name": "es6-full-brotli",
     "path": "lib/dist/es6/mod/ts-utils.js",
-    "limit": "10.5 kb",
+    "limit": "11 kb",
     "brotli": true,
     "running": false
   },
   {
     "name": "es5-zip",
     "path": "lib/dist/es5/mod/ts-utils.js",
-    "limit": "11.5 Kb",
+    "limit": "12 Kb",
     "gzip": true,
     "running": false
   },
   {
     "name": "es6-zip",
     "path": "lib/dist/es6/mod/ts-utils.js",
-    "limit": "11.5 Kb",
+    "limit": "12 Kb",
     "gzip": true,
     "running": false
   },

README.md

@@ -28,6 +28,7 @@ If you find this library useful, please consider [sponsoring @nevware21](https:/
 
 ### Advanced Topics
 - **[Advanced Deep Copy Functionality](./advanced-deep-copy.md)** - Using custom handlers with deep copy operations
+- **[Security Helpers](./security-helpers.md)** - Preventing prototype pollution during object copy and merge operations
 - **[Performance and Minification Benefits](./usage-guide.md#performance-and-minification-benefits)** - Understanding how the library optimizes for performance
 - **[Timeout Overrides](./timeout-overrides.md)** - Using Timeout overrides for custom scheduling behavior
 - **[Bundle Size Optimization](./size-optimization.md)** - Detailed byte-level measurements and strategies for reducing bundle size

docs/README.md

@@ -0,0 +1,49 @@
+# Security Helpers
+
+When copying, merging, or transforming untrusted object-like input, JavaScript applications can accidentally allow prototype pollution via dangerous keys such as `__proto__`, `constructor`, and `prototype`.
+
+This package includes helpers to reduce that risk in common object traversal and assignment flows.
+
+## Available Helpers
+
+- [forEachOwnKeySafe](./typedoc/functions/forEachOwnKeySafe.html) safely iterates only own enumerable keys and skips dangerous property names.
+- [isUnsafePropKey](./typedoc/functions/isUnsafePropKey.html) identifies keys commonly used for prototype pollution attacks.
+- [isUnsafeTarget](./typedoc/functions/isUnsafeTarget.html) detects built-in prototype objects so you can avoid mutating native prototypes.
+
+## Recommended Usage
+
+Use `isUnsafeTarget()` to guard the destination object, and `forEachOwnKeySafe()` to iterate source keys.
+
+```typescript
+import {
+  forEachOwnKeySafe,
+  isUnsafeTarget
+} from "@nevware21/ts-utils";
+
+function copyTrustedValues(source: any, target: any) {
+  if (isUnsafeTarget(target)) {
+    throw new TypeError("Refusing to write to a built-in prototype");
+  }
+
+  forEachOwnKeySafe(source, (key, value) => {
+    target[key] = value;
+  });
+
+  return target;
+}
+
+const payload = {
+  safe: true,
+  __proto__: {
+    polluted: true
+  }
+};
+
+copyTrustedValues(payload, {});
+// Result only includes the safe enumerable keys.
+```
+
+## Notes
+
+- These helpers provide safer defaults, but they do not replace application-level input validation.
+- If you accept untrusted JSON or query-derived objects, validate schema and value types before assignment.

docs/security-helpers.md

@@ -148,7 +148,23 @@
         "object-keys",
         "lightweight",
         "performance-optimized",
-        "type-safe"
+        "type-safe",
+        "prototype-pollution",
+        "prototype-pollution-prevention",
+        "secure-merge",
+        "secure-copy",
+        "object-security",
+        "defensive-programming",
+        "forEachOwnKeySafe",
+        "isUnsafePropKey",
+        "isUnsafeTarget",
+        "arrKeys",
+        "arrIndexKeys",
+        "sparse-array",
+        "array-like",
+        "from-entries",
+        "has-own",
+        "base64"
     ],
     "types": "./dist/types/ts-utils.d.ts",
     "main": "./dist/es5/main/ts-utils.js",

lib/package.json

@@ -0,0 +1,51 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+import { getLength } from "../helpers/length";
+import { _throwIfNullOrUndefined } from "../internal/throwIf";
+import { mathToInt } from "../math/to_int";
+import { objHasOwn } from "../object/has_own";
+
+/**
+ * Returns only present own numeric index keys for an array-like value.
+ *
+ * Unlike {@link arrKeys}, this skips holes / missing indexes.
+ * For example, an array with indexes `0`, `1`, `2`, `10` returns `[0, 1, 2, 10]`.
+ * @since 0.14.0
+ * @group Array
+ * @group ArrayLike
+ * @param value - The array-like value to enumerate.
+ * @returns An array containing only present own numeric index keys.
+ * @example
+ * ```ts
+ * arrIndexKeys(["a", "b", "c"]);
+ * // [0, 1, 2]
+ *
+ * const sparse: any[] = [];
+ * sparse[0] = "a";
+ * sparse[10] = "z";
+ * arrIndexKeys(sparse);
+ * // [0, 10]
+ * ```
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export function arrIndexKeys<T = any>(value: ArrayLike<T>): number[] {
+    _throwIfNullOrUndefined(value);
+
+    let keys: number[] = [];
+    let len = mathToInt(getLength(value));
+    if (len > 0) {
+        for (let lp = 0; lp < len; lp++) {
+            if (objHasOwn(value, lp)) {
+                keys.push(lp);
+            }
+        }
+    }
+
+    return keys;
+}

lib/src/array/arrIndexKeys.ts

@@ -0,0 +1,79 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+import { ArrProto } from "../internal/constants";
+import { _throwIfNullOrUndefined } from "../internal/throwIf";
+import { _unwrapFunctionWithPoly } from "../internal/unwrapFunction";
+import { createIterableIterator } from "../iterator/create";
+import { mathToInt } from "../math/to_int";
+
+/**
+ * Returns an iterator over all numeric keys from `0` to `length - 1`.
+ *
+ * This uses `Array.prototype.keys()` when available and falls back to {@link polyArrKeys}.
+ * Unlike {@link arrIndexKeys}, this always iterates all index positions, including holes.
+ * @since 0.14.0
+ * @function
+ * @group Array
+ * @group ArrayLike
+ * @group Iterator
+ * @param value - The array-like value to get key iterator for.
+ * @returns An iterable iterator of numeric index keys.
+ * @example
+ * ```ts
+ * arrFrom(arrKeys(["a", "b", "c"]));
+ * // [0, 1, 2]
+ *
+ * const sparse: any[] = [];
+ * sparse[2] = "c";
+ * arrFrom(arrKeys(sparse));
+ * // [0, 1, 2]
+ * ```
+ */
+export const arrKeys: <T = any>(value: ArrayLike<T>) => IterableIterator<number> = (/*#__PURE__*/_unwrapFunctionWithPoly("keys", ArrProto as any, polyArrKeys) as any);
+
+/**
+ * Polyfill implementation of `Array.prototype.keys()` for array-like values.
+ * @since 0.14.0
+ * @group Array
+ * @group ArrayLike
+ * @group Iterator
+ * @group Polyfill
+ * @param value - The array-like value to get key iterator for.
+ * @returns An iterable iterator of numeric index keys.
+ * @example
+ * ```ts
+ * arrFrom(polyArrKeys(["a", "b", "c"]));
+ * // [0, 1, 2]
+ *
+ * arrFrom(polyArrKeys({ length: 3, 0: "a", 2: "c" }));
+ * // [0, 1, 2]
+ * ```
+ */
+/*#__NO_SIDE_EFFECTS__*/
+export function polyArrKeys<T = any>(value: ArrayLike<T>): IterableIterator<number> {
+    _throwIfNullOrUndefined(value);
+
+    let idx = -1;
+    let len = mathToInt(value.length);
+    if (len < 0) {
+        len = 0;
+    }
+
+    return createIterableIterator<number>({
+        n: function() {
+            idx++;
+            let isDone = idx >= len;
+            if (!isDone) {
+                this.v = idx;
+            }
+
+            return isDone;
+        }
+    });
+}

lib/src/array/arrKeys.ts

@@ -7,7 +7,9 @@
  */
 
 import { isArrayLike, isFunction } from "../helpers/base";
+import { objDefine } from "../object/define";
 import { objHasOwn } from "../object/has_own";
+import { isUnsafePropKey } from "../object/isUnsafePropKey";
 import { asString } from "../string/as_string";
 import { isSymbol } from "../symbol/symbol";
 import { arrForEach } from "./forEach";
@@ -104,7 +106,11 @@ export function arrGroupBy<T>(
             const theKey = isSymbol(keyVal) ? keyVal : asString(keyVal);
 
             if (!objHasOwn(result, theKey)) {
-                result[theKey] = [];
+                if (isUnsafePropKey(theKey)) {
+                    objDefine(result, theKey, { v: [] });
+                } else {
+                    result[theKey] = [];
+                }
             }
 
             result[theKey].push(item);