Add API defining behaviour to apiManipulation (#1771)

* Add API defining behaviour to apiManipulation

* Simplify unit test

* Fix linting

* Pass correct params in unit test

Author: jonathanKingston

injected/integration-test/test-pages/api-manipulation/config/apis.json

@@ -82,6 +82,21 @@
                         "getterValue": {
                             "type": "undefined"
                         }
+                    },
+                    "window.definedByConfig": {
+                        "type": "descriptor",
+                        "getterValue": {
+                            "type": "string",
+                            "value": "defined!"
+                        },
+                        "define": true
+                    },
+                    "window.notDefinedByConfig": {
+                        "type": "descriptor",
+                        "getterValue": {
+                            "type": "string",
+                            "value": "should not exist"
+                        }
                     }
                 }
             }

injected/integration-test/test-pages/api-manipulation/pages/apis.html

@@ -89,6 +89,21 @@
             return result;
         });
 
+        test('Define property with define: true', async () => {
+            return [
+                {
+                    name: "Property defined by config (define: true)",
+                    result: window.definedByConfig,
+                    expected: "defined!"
+                },
+                {
+                    name: "Property not defined by config (define not set)",
+                    result: window.notDefinedByConfig,
+                    expected: undefined
+                }
+            ];
+        });
+
         // eslint-disable-next-line no-undef
         renderResults();
     </script>

injected/src/features/api-manipulation.js

@@ -4,10 +4,10 @@
  *
  * @module API manipulation
  */
-import ContentFeature from '../content-feature';
+import ContentFeature from '../content-feature.js';
 // eslint-disable-next-line no-redeclare
-import { hasOwnProperty } from '../captured-globals';
-import { processAttr } from '../utils';
+import { hasOwnProperty } from '../captured-globals.js';
+import { processAttr } from '../utils.js';
 
 /**
  * @internal
@@ -51,6 +51,9 @@ export default class ApiManipulation extends ContentFeature {
             if (change.configurable && typeof change.configurable !== 'boolean') {
                 return false;
             }
+            if ('define' in change && typeof change.define !== 'boolean') {
+                return false;
+            }
             return typeof change.getterValue !== 'undefined';
         }
         return false;
@@ -65,6 +68,7 @@ export default class ApiManipulation extends ContentFeature {
      * @property {import('../utils.js').ConfigSetting} [getterValue] - The value returned from a getter.
      * @property {boolean} [enumerable] - Whether the property is enumerable.
      * @property {boolean} [configurable] - Whether the property is configurable.
+     * @property {boolean} [define] - Whether to define the property if it does not exist.
      */
 
     /**
@@ -117,6 +121,17 @@ export default class ApiManipulation extends ContentFeature {
             if ('configurable' in change) {
                 descriptor.configurable = change.configurable;
             }
+            // If 'define' is true and property does not exist, define it directly
+            if (change.define === true && !(key in api)) {
+                // Ensure descriptor has required boolean fields
+                const defineDescriptor = {
+                    ...descriptor,
+                    enumerable: typeof descriptor.enumerable !== 'boolean' ? true : descriptor.enumerable,
+                    configurable: typeof descriptor.configurable !== 'boolean' ? true : descriptor.configurable,
+                };
+                this.defineProperty(api, key, defineDescriptor);
+                return;
+            }
             this.wrapProperty(api, key, descriptor);
         }
     }

injected/unit-test/features.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import { readFile } from 'fs/promises';
 import * as glob from 'glob';
 import { formatErrors } from '@duckduckgo/privacy-configuration/tests/schema-validation.js';
+import ApiManipulation from '../src/features/api-manipulation.js';
 
 // TODO: Ignore eslint redeclare as we're linting for esm and cjs
 // eslint-disable-next-line no-redeclare
@@ -114,3 +115,55 @@ describe('test-pages/*/config/*.json schema validation', () => {
         });
     }
 });
+
+describe('ApiManipulation', () => {
+    let apiManipulation;
+    let dummyTarget;
+
+    beforeEach(() => {
+        apiManipulation = new ApiManipulation(
+            'apiManipulation',
+            {},
+            {
+                bundledConfig: { features: { apiManipulation: { state: 'enabled', exceptions: [] } } },
+                site: { domain: 'test.com' },
+                platform: { version: '1.0.0' },
+            },
+        );
+        dummyTarget = {};
+    });
+
+    it('defines a new property if define: true is set and property does not exist', () => {
+        const change = {
+            type: 'descriptor',
+            getterValue: { type: 'string', value: 'defined!' },
+            define: true,
+        };
+        apiManipulation.wrapApiDescriptor(dummyTarget, 'definedByConfig', change);
+        expect(dummyTarget.definedByConfig).toBe('defined!');
+    });
+
+    it('does not define a property if define is not set and property does not exist', () => {
+        const change = {
+            type: 'descriptor',
+            getterValue: { type: 'string', value: 'should not exist' },
+        };
+        apiManipulation.wrapApiDescriptor(dummyTarget, 'notDefinedByConfig', change);
+        expect(dummyTarget.notDefinedByConfig).toBeUndefined();
+    });
+
+    it('wraps an existing property if present', () => {
+        Object.defineProperty(dummyTarget, 'hardwareConcurrency', {
+            get: () => 4,
+            configurable: true,
+            enumerable: true,
+        });
+        const change = {
+            type: 'descriptor',
+            getterValue: { type: 'number', value: 222 },
+        };
+        apiManipulation.wrapApiDescriptor(dummyTarget, 'hardwareConcurrency', change);
+        // The getter should now return 222
+        expect(dummyTarget.hardwareConcurrency).toBe(222);
+    });
+});