shelving 1.267.2 → 1.267.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.267.2",
+	"version": "1.267.3",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/util/dictionary.d.ts

@@ -163,6 +163,7 @@ export declare const omitDictionaryItem: <T>(dict: ImmutableDictionary<T>, key:
 export declare const pickDictionaryItems: <T>(dict: ImmutableDictionary<T>, ...keys: string[]) => ImmutableDictionary<T>;
 /**
  * Set a single named item on a dictionary object (by reference) and return its value.
+ * - The key is trusted by contract: a runtime-untrusted key like `"__proto__"` would mutate the target's prototype, so validate or filter untrusted keys before calling (or use a null-prototype target).
  *
  * @param dict The dictionary to set the item on (modified by reference).
  * @param key The key of the item to set.
@@ -173,6 +174,7 @@ export declare const pickDictionaryItems: <T>(dict: ImmutableDictionary<T>, ...k
 export declare const setDictionaryItem: <T>(dict: MutableDictionary<T>, key: string, value: T) => T;
 /**
  * Set several named items on a dictionary object (by reference).
+ * - Keys are trusted by contract: a runtime-untrusted key like `"__proto__"` would mutate the target's prototype, so validate or filter untrusted keys before calling (or use a null-prototype target).
  *
  * @param dict The dictionary to set the items on (modified by reference).
  * @param entries The items to set, as a dictionary or iterable set of key/value entry tuples.

package/util/dictionary.js

@@ -139,6 +139,7 @@ export const omitDictionaryItem = omitProps;
 export const pickDictionaryItems = pickProps;
 /**
  * Set a single named item on a dictionary object (by reference) and return its value.
+ * - The key is trusted by contract: a runtime-untrusted key like `"__proto__"` would mutate the target's prototype, so validate or filter untrusted keys before calling (or use a null-prototype target).
  *
  * @param dict The dictionary to set the item on (modified by reference).
  * @param key The key of the item to set.
@@ -149,6 +150,7 @@ export const pickDictionaryItems = pickProps;
 export const setDictionaryItem = setProp;
 /**
  * Set several named items on a dictionary object (by reference).
+ * - Keys are trusted by contract: a runtime-untrusted key like `"__proto__"` would mutate the target's prototype, so validate or filter untrusted keys before calling (or use a null-prototype target).
  *
  * @param dict The dictionary to set the items on (modified by reference).
  * @param entries The items to set, as a dictionary or iterable set of key/value entry tuples.

package/util/diff.d.ts

@@ -44,6 +44,7 @@ export declare function deepDiffArray<R extends ImmutableArray>(left: ImmutableA
  * @returns Object containing the missing/updated properties that `left` needs to become `right`.
  * - If the two values are deeply equal the `SAME` constant is returned.
  * - If `left` isn't an object then the result can't be diffed so entire `right` is returned.
+ * - Diff object has a `null` prototype, so an untrusted `"__proto__"` key in `right` becomes an inert own property instead of injecting a prototype.
  * @see https://shelving.cc/util/diff/deepDiffObject
  */
 export declare function deepDiffObject<R extends ImmutableObject>(left: ImmutableObject, right: R): R | DeepPartial<R> | typeof SAME;

package/util/diff.js

@@ -42,7 +42,10 @@ export function deepDiffObject(left, right) {
     // If left is empty, entire right is returned.
     if (!leftKeys.length)
         return rightKeys.length ? right : SAME;
-    const diff = {};
+    // Null-prototype accumulator: an untrusted `"__proto__"` key in `right` then becomes an inert own property
+    // instead of invoking the inherited `__proto__` setter, so a crafted `{ "__proto__": … }` input can't reassign
+    // the diff object's prototype.
+    const diff = Object.create(null);
     let changed = false;
     for (const k of rightKeys) {
         const d = deepDiff(left[k], right[k]);

package/util/merge.d.ts

@@ -67,6 +67,7 @@ export declare function mergeArray<L, R>(left: ImmutableArray<L>, right: Immutab
  * - Only works on enumerable own keys (as returned by `Object.keys()`).
  * - Always returns a new object (or the `left` object if no changes were made).
  * - Resulting object is `cleaned`, i.e. properties in `left` or `right` that are `undefined` will be removed from the merged object.
+ * - Merged object has a `null` prototype, so an untrusted `"__proto__"` key in `right` becomes an inert own property instead of injecting a prototype.
  *
  * @param left The left object to merge into.
  * @param right The right object whose props replace or merge with `left`.

package/util/merge.js

@@ -45,7 +45,10 @@ export function mergeObject(left, right, recursor = exactMerge) {
     if (!rightEntries.length)
         return left;
     const leftKeys = Object.keys(left);
-    const merged = { ...left };
+    // Null-prototype accumulator: an untrusted `"__proto__"` key in `right` then becomes an inert own property
+    // instead of invoking the inherited `__proto__` setter, so a crafted `{ "__proto__": … }` input can't reassign
+    // the merged object's prototype.
+    const merged = Object.assign(Object.create(null), left);
     let changed = false;
     for (const [k, r] of rightEntries) {
         if (leftKeys.includes(k)) {

package/util/object.d.ts

@@ -249,6 +249,7 @@ export declare const omitProp: <T, K extends Key<T>>(input: T, key: K) => Omit<T
 export declare function pickProps<T, K extends Key<T>>(obj: T, ...keys: K[]): Pick<T, K>;
 /**
  * Set a single named prop on an object (by reference) and return its value.
+ * - The key is trusted by contract: a runtime-untrusted key like `"__proto__"` would mutate the target's prototype, so validate or filter untrusted keys before calling (or use a null-prototype target).
  *
  * @param obj The object to set the prop on (modified by reference).
  * @param key The key of the prop to set.
@@ -259,6 +260,7 @@ export declare function pickProps<T, K extends Key<T>>(obj: T, ...keys: K[]): Pi
 export declare function setProp<T extends MutableObject, K extends Key<T>>(obj: T, key: K, value: T[K]): T[K];
 /**
  * Set several named props on an object (by reference).
+ * - Keys are trusted by contract: a runtime-untrusted key like `"__proto__"` would mutate the target's prototype, so validate or filter untrusted keys before calling (or use a null-prototype target).
  *
  * @param obj The object to set the props on (modified by reference).
  * @param entries The props to set, as an object or iterable set of key/value entry tuples.

package/util/object.js

@@ -157,6 +157,7 @@ function _hasKey([key]) {
 }
 /**
  * Set a single named prop on an object (by reference) and return its value.
+ * - The key is trusted by contract: a runtime-untrusted key like `"__proto__"` would mutate the target's prototype, so validate or filter untrusted keys before calling (or use a null-prototype target).
  *
  * @param obj The object to set the prop on (modified by reference).
  * @param key The key of the prop to set.
@@ -170,6 +171,7 @@ export function setProp(obj, key, value) {
 }
 /**
  * Set several named props on an object (by reference).
+ * - Keys are trusted by contract: a runtime-untrusted key like `"__proto__"` would mutate the target's prototype, so validate or filter untrusted keys before calling (or use a null-prototype target).
  *
  * @param obj The object to set the props on (modified by reference).
  * @param entries The props to set, as an object or iterable set of key/value entry tuples.

package/util/uri.d.ts

@@ -192,6 +192,7 @@ export type PossibleURIParams = PossibleURI | URLSearchParams | ImmutableDiction
 /**
  * Get a set of params for a URI as a dictionary.
  * - Any params with `undefined` value will be ignored.
+ * - Returned dictionary has a `null` prototype, so an untrusted `__proto__` param becomes an inert own entry (instead of being silently dropped by the inherited `__proto__` setter).
  *
  * @param params Possible URI params to convert.
  * @param caller Function to attribute a thrown error to (defaults to `getURIParams` itself).

package/util/uri.js

@@ -99,6 +99,7 @@ function* getURIEntries(params, caller = getURIParams) {
 /**
  * Get a set of params for a URI as a dictionary.
  * - Any params with `undefined` value will be ignored.
+ * - Returned dictionary has a `null` prototype, so an untrusted `__proto__` param becomes an inert own entry (instead of being silently dropped by the inherited `__proto__` setter).
  *
  * @param params Possible URI params to convert.
  * @param caller Function to attribute a thrown error to (defaults to `getURIParams` itself).
@@ -108,7 +109,9 @@ function* getURIEntries(params, caller = getURIParams) {
  * @see https://shelving.cc/util/uri/getURIParams
  */
 export function getURIParams(params, caller = getURIParams) {
-    const output = {};
+    // Null-prototype accumulator: param keys are runtime-untrusted, so an untrusted `"__proto__"` key becomes an
+    // inert own entry instead of invoking the inherited `__proto__` setter (which would silently drop the param).
+    const output = Object.create(null);
     for (const [key, str] of getURIEntries(params, caller))
         output[key] = str;
     return output;