@openmrs/esm-expression-evaluator 10.0.1-pre.5420 → 10.0.1-pre.5434

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 5 files with swc (286.5ms)
+[0] Successfully compiled: 5 files with swc (242.27ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/README.md

@@ -1,3 +1,27 @@
 # openmrs-esm-expression-evaluator
 
 openmrs-esm-expression-evaluator provides functions to allow evaluating user-defined expressions in a way safer than eval.
+
+## Writing null-safe expressions
+
+Member access on `null` or `undefined` is an error, as it is in JavaScript, so an expression that runs
+against data which may not have loaded yet needs a guard. `&&`, `||` and `??` short-circuit, and optional
+chaining is supported, so any of these work:
+
+```js
+session?.user ? session.user.privileges.some((p) => p.display === 'Some Privilege') : false;
+session && session.user && session.user.privileges.length > 0;
+```
+
+A short circuit abandons the rest of the chain rather than a single access, so `a?.b.c.d` is `undefined`
+when `a` is nullish. A property that is genuinely missing is still an error: `a?.b.c` throws when `a` is
+`{}`, because `a.b` is undefined for reasons optional chaining says nothing about.
+
+## What the sandbox guarantees
+
+Expressions are interpreted from a jsep AST; they are never compiled or run by the JS engine. The
+interpreter supports only the expression language, so there is no assignment, no statements, no object
+literals, and no `this`. Inline arrow functions *are* supported, since callbacks like
+`arr.find((v) => v === needle)` are a large part of what expressions are for; what is prohibited is
+building a function from a string, which is what an escape to the `Function` constructor would give you.
+An expression sees nothing but the `variables` it is handed and the small set of globals in `globals.ts`.

package/dist/evaluator.js

@@ -305,11 +305,11 @@ function visitExpression(expression, context) {
         case 'ConditionalExpression':
             return visitConditionalExpression(expression, context);
         case 'CallExpression':
-            return visitCallExpression(expression, context);
+            return unwrapShortCircuit(visitCallExpression(expression, context));
         case 'ArrowFunctionExpression':
             return visitArrowFunctionExpression(expression, context);
         case 'MemberExpression':
-            return visitMemberExpression(expression, context);
+            return unwrapShortCircuit(visitMemberExpression(expression, context));
         case 'ArrayExpression':
             return visitArrayExpression(expression, context);
         case 'SequenceExpression':
@@ -356,6 +356,15 @@ function visitUnaryExpression(expression, context) {
     }
 }
 function visitBinaryExpression(expression, context) {
+    // these binary operators are meant to short-circuit
+    switch(expression.operator){
+        case '&&':
+            return visitExpression(expression.left, context) && visitExpression(expression.right, context);
+        case '||':
+            return visitExpression(expression.left, context) || visitExpression(expression.right, context);
+        case '??':
+            return visitExpression(expression.left, context) ?? visitExpression(expression.right, context);
+    }
     let left = visitExpression(expression.left, context);
     let right = visitExpression(expression.right, context);
     switch(expression.operator){
@@ -389,12 +398,6 @@ function visitBinaryExpression(expression, context) {
             return left <= right;
         case 'in':
             return left in right;
-        case '&&':
-            return left && right;
-        case '||':
-            return left || right;
-        case '??':
-            return left ?? right;
         default:
             throw `Expression evaluator does not support operator '${expression.operator}' operator`;
     }
@@ -404,8 +407,16 @@ function visitConditionalExpression(expression, context) {
     return test ? visitExpression(expression.consequent, context) : visitExpression(expression.alternate, context);
 }
 function visitCallExpression(expression, context) {
+    let callee = visitChainOperand(expression.callee, context);
+    if (callee === shortCircuit) {
+        return shortCircuit;
+    }
+    // `cb?.()` abandons the chain before its arguments are evaluated, so this has to come first; otherwise
+    // an argument's side effects happen for a call that never takes place
+    if (expression.optional && (callee === null || callee === undefined)) {
+        return shortCircuit;
+    }
     let args = expression.arguments?.map(handleNullableExpression(context));
-    let callee = visitExpression(expression.callee, context);
     if (!callee) {
         throw `No function named ${getCallTargetName(expression.callee)} is defined in this context`;
     } else if (!(typeof callee === 'function')) {
@@ -437,10 +448,19 @@ function visitArrowFunctionExpression(expression, context) {
             return acc;
         }, []));
         return visitExpression(expression.body, context.addVariables(vars));
-    }).bind(context.thisObj ?? null);
+    }).bind(null);
 }
 function visitMemberExpression(expression, context) {
-    let obj = visitExpression(expression.object, context);
+    const obj = visitChainOperand(expression.object, context);
+    if (obj === shortCircuit) {
+        return shortCircuit;
+    }
+    if (expression.optional && (obj === null || obj === undefined)) {
+        return shortCircuit;
+    }
+    if (obj === null) {
+        throw TypeError(`TypeError: cannot read properties of null (reading '${describePropertyName(expression.property, context)}')`);
+    }
     if (obj === undefined) {
         switch(expression.object.type){
             case 'Identifier':
@@ -450,43 +470,21 @@ function visitMemberExpression(expression, context) {
                 }
             case 'MemberExpression':
                 {
-                    let propertyName = visitExpressionName(expression.property, context);
-                    throw TypeError(`TypeError: cannot read properties of undefined (reading '${propertyName}')`);
+                    throw TypeError(`TypeError: cannot read properties of undefined (reading '${describePropertyName(expression.property, context)}')`);
                 }
             default:
                 throw `VisitMemberExpression does not support operator '${expression.object.type}' type`;
         }
     }
-    let newObj = obj;
-    if (typeof obj === 'string') {
-        newObj = String.prototype;
-    } else if (typeof obj === 'number') {
-        newObj = Number.prototype;
-    } else if (typeof obj === 'function') {
-    // no-op
-    } else if (typeof obj !== 'object') {
+    if (typeof obj !== 'object' && typeof obj !== 'function' && typeof obj !== 'string' && typeof obj !== 'number') {
         throw `VisitMemberExpression does not support member access on type ${typeof obj}`;
     }
-    context.thisObj = newObj;
-    let result;
-    switch(expression.property.type){
-        case 'Identifier':
-        case 'MemberExpression':
-            result = visitExpression(expression.property, context);
-            break;
-        default:
-            {
-                const property = visitExpression(expression.property, context);
-                if (typeof property === 'undefined') {
-                    throw {
-                        type: 'Illegal property access',
-                        message: 'No property was supplied to the property access'
-                    };
-                }
-                validatePropertyName(property);
-                result = obj[property];
-            }
-    }
+    // `a.b` names its property statically; `a[b]` evaluates it, so the result has to be turned into the
+    // exact key the indexer will use before it can be validated
+    const key = expression.computed ? toPropertyKey(visitExpression(expression.property, context)) : staticPropertyName(expression.property);
+    validatePropertyName(key);
+    validatePropertyAccess(obj, key);
+    const result = obj[key];
     if (typeof result === 'function') {
         return result.bind(obj);
     }
@@ -533,26 +531,15 @@ function visitTemplateElement(expression, context) {
 }
 function visitIdentifier(expression, context) {
     validatePropertyName(expression.name);
-    // we support both `object` and `function` in the same way as technically property access on functions
-    // is possible; the use-case here is to support JS's "static" functions like `Number.isInteger()`, which
-    // is technically reading a property on a function
-    const thisObj = context.thisObj;
-    if (thisObj && (typeof thisObj === 'object' || typeof thisObj === 'function') && expression.name in thisObj) {
-        const result = thisObj[expression.name];
-        validatePropertyName(result);
-        return result;
-    } else if (context.variables && expression.name in context.variables) {
-        const result = context.variables[expression.name];
-        validatePropertyName(result);
-        return result;
-    } else if (expression.name in context.globals) {
+    if (context.variables && Object.hasOwn(context.variables, expression.name)) {
+        return context.variables[expression.name];
+    } else if (Object.hasOwn(context.globals, expression.name)) {
         return context.globals[expression.name];
     } else {
         return undefined;
     }
 }
 function visitLiteral(expression, context) {
-    validatePropertyName(expression.value);
     return expression.value;
 }
 function createSynchronousContext(variables) {
@@ -563,7 +550,6 @@ function createAsynchronousContext(variables) {
 }
 function createContextInternal(variables, globals_) {
     const context = {
-        thisObj: undefined,
         variables: {
             ...variables
         },
@@ -581,6 +567,30 @@ function createContextInternal(variables, globals_) {
     context.addVariables.bind(context);
     return context;
 }
+/**
+ * Marks that an optional link (`a?.b`) found a nullish value. Optional chaining abandons the rest of the
+ * chain rather than just the one access, so this is returned in place of a value and passed along by each
+ * member access and call until it reaches the end of the chain, where {@link unwrapShortCircuit} turns it
+ * into `undefined`. It has to be distinguishable from a real `undefined`, since `a.b.c` where `a.b` is
+ * genuinely undefined is still an error.
+ */ const shortCircuit = Symbol('optional chain short-circuited');
+/**
+ * Visits the object of a member access or the callee of a call, i.e. a link in a chain rather than the end
+ * of one. Dispatching directly keeps a short circuit intact, where {@link visitExpression} would have
+ * already flattened it to `undefined`.
+ */ function visitChainOperand(expression, context) {
+    switch(expression.type){
+        case 'MemberExpression':
+            return visitMemberExpression(expression, context);
+        case 'CallExpression':
+            return visitCallExpression(expression, context);
+        default:
+            return visitExpression(expression, context);
+    }
+}
+function unwrapShortCircuit(result) {
+    return result === shortCircuit ? undefined : result;
+}
 // helper useful for handling arrays of expressions, since `null` expressions should not be
 // dispatched to `visitExpression()`
 function handleNullableExpression(context) {
@@ -599,6 +609,67 @@ function validatePropertyName(name) {
         };
     }
 }
+/**
+ * Returns the name of a statically-accessed property, i.e. the `b` of `a.b`. jsep only ever parses an
+ * identifier here, so anything else means we were handed an AST we did not build.
+ */ function staticPropertyName(expression) {
+    if (expression.type !== 'Identifier') {
+        throw `VisitMemberExpression does not support a property of type '${expression.type}'`;
+    }
+    return expression.name;
+}
+/**
+ * Narrows the result of a computed property expression to the key that `obj[key]` would actually read.
+ * Anything else is refused rather than converted: JS applies ToPropertyKey to whatever it is given, so a
+ * value like `['const' + 'ructor']` reads `constructor` even though it compares equal to nothing.
+ */ function toPropertyKey(value) {
+    if (typeof value === 'undefined') {
+        throw {
+            type: 'Illegal property access',
+            message: 'No property was supplied to the property access'
+        };
+    }
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw {
+            type: 'Illegal property access',
+            message: `Cannot use a value of type ${value === null ? 'null' : typeof value} as a property name`
+        };
+    }
+    return value;
+}
+/** Properties of `Object.prototype` that are harmless enough to leave reachable */ const safeBasePropertyNames = new Set([
+    'toString',
+    'valueOf',
+    'hasOwnProperty'
+]);
+/**
+ * Refuses any property that resolves on `Object.prototype` or `Function.prototype`.
+ */ function validatePropertyAccess(obj, key) {
+    if (safeBasePropertyNames.has(String(key))) {
+        return;
+    }
+    // primitives are boxed so that `hasOwn()` sees a string's `length` and indices
+    let holder = Object(obj);
+    while(holder !== null){
+        if (Object.hasOwn(holder, key)) {
+            if (holder === Object.prototype || holder === Function.prototype) {
+                throw {
+                    type: 'Illegal property access',
+                    message: `Cannot access the ${key} property of objects`
+                };
+            }
+            return;
+        }
+        holder = Object.getPrototypeOf(holder);
+    }
+}
+/** Best-effort name for a property, used only to build error messages */ function describePropertyName(expression, context) {
+    try {
+        return visitExpressionName(expression, context);
+    } catch  {
+        return '<computed>';
+    }
+}
 function isValidVariableType(val) {
     if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean' || typeof val === 'function' || val === null || val instanceof RegExp) {
         return true;

package/dist/extractor.js

@@ -123,6 +123,11 @@ function visitArrowFunctionExpression(expression, context) {
 }
 function visitMemberExpression(expression, context) {
     visitExpression(expression.object, context);
+    // the `b` of `a[b]` is a variable the caller has to supply, whereas the `b` of `a.b` is a property name
+    if (expression.computed) {
+        visitExpression(expression.property, context);
+        return;
+    }
     const newContext = {
         ...context
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-expression-evaluator",
-  "version": "10.0.1-pre.5420",
+  "version": "10.0.1-pre.5434",
   "license": "MPL-2.0",
   "description": "Utilities for evaluating user-defined expressions",
   "type": "module",

package/src/evaluator.test.ts

@@ -88,6 +88,150 @@ describe('OpenMRS Expression Evaluator', () => {
     expect(() => evaluate('a[b]', { a: {}, b: 'prototype' })).toThrow(/Cannot access the prototype property .*/i);
   });
 
+  it('should not support constructor references', () => {
+    expect(() => evaluate('a.constructor', { a: {} })).toThrow(/Cannot access the constructor property .*/i);
+    expect(() => evaluate('a["constructor"]', { a: {} })).toThrow(/Cannot access the constructor property .*/i);
+    expect(() => evaluate("a['const' + 'ructor']", { a: {} })).toThrow(/Cannot access the constructor property .*/i);
+    expect(() => evaluate('a[b]', { a: {}, b: 'constructor' })).toThrow(/Cannot access the constructor property .*/i);
+    expect(() => evaluate('String.constructor')).toThrow(/Cannot access the constructor property .*/i);
+  });
+
+  // A computed property is coerced by ToPropertyKey, so a non-string key whose string conversion is
+  // `constructor` used to read `constructor` while comparing equal to nothing the guard knew about.
+  it('should not allow a non-string computed property to name a property', () => {
+    expect(() => evaluate("String[['const' + 'ructor']]('return 1')()")).toThrow(
+      /Cannot use a value of type object as a property name/i,
+    );
+    expect(() => evaluate("(() => 1)[['const' + 'ructor']]('return 1')()")).toThrow(
+      /Cannot use a value of type object as a property name/i,
+    );
+    expect(() => evaluate("String['con'.concat('structor').split('|')]")).toThrow(
+      /Cannot use a value of type object as a property name/i,
+    );
+    expect(() => evaluate("String[Array.of('const' + 'ructor')]")).toThrow(
+      /Cannot use a value of type object as a property name/i,
+    );
+    expect(() => evaluate("a[[['__pro' + 'to__']]]", { a: {} })).toThrow(
+      /Cannot use a value of type object as a property name/i,
+    );
+    expect(() => evaluate('a[b]', { a: {}, b: true })).toThrow(
+      /Cannot use a value of type boolean as a property name/i,
+    );
+    expect(() => evaluate('a[b]', { a: {}, b: null })).toThrow(/Cannot use a value of type null as a property name/i);
+  });
+
+  // `Object.prototype` and `Function.prototype` hold every generic route back to the host realm, so no
+  // property that resolves on either of them should be readable, however the key is spelled.
+  it('should not expose Object.prototype or Function.prototype members', () => {
+    const fn = () => 1;
+    expect(() => evaluate("f['ca' + 'll']", { f: fn })).toThrow(/Cannot access the call property .*/i);
+    expect(() => evaluate('f.apply', { f: fn })).toThrow(/Cannot access the apply property .*/i);
+    expect(() => evaluate('f.bind', { f: fn })).toThrow(/Cannot access the bind property .*/i);
+    expect(() => evaluate("a['__define' + 'Getter__']", { a: {} })).toThrow(
+      /Cannot access the __defineGetter__ property .*/i,
+    );
+    expect(() => evaluate("a['__lookup' + 'Getter__']", { a: {} })).toThrow(
+      /Cannot access the __lookupGetter__ property .*/i,
+    );
+    expect(() => evaluate('a.isPrototypeOf', { a: {} })).toThrow(/Cannot access the isPrototypeOf property .*/i);
+    // identifiers must not reach them through the variables or globals maps either
+    expect(evaluate('toString')).toBeUndefined();
+    expect(evaluate('hasOwnProperty')).toBeUndefined();
+  });
+
+  it('should still allow harmless base properties and builtins on their own prototypes', () => {
+    expect(evaluate('a.toString()', { a: {} })).toBe('[object Object]');
+    expect(evaluate('a.valueOf()', { a: 1 })).toBe(1);
+    expect(evaluate('"abc".toUpperCase()')).toBe('ABC');
+    expect(evaluate('a.length', { a: [1, 2, 3] })).toBe(3);
+    expect(evaluate('f.name', { f: function named() {} })).toBe('named');
+  });
+
+  // `evaluateAsync()` shares the visitor, so every guard has to hold there too
+  it('should apply the same guards asynchronously', async () => {
+    await expect(evaluateAsync("String[['const' + 'ructor']]('return 1')()")).rejects.toThrow(
+      /Cannot use a value of type object as a property name/i,
+    );
+    await expect(evaluateAsync('a.constructor', { a: {} })).rejects.toThrow(
+      /Cannot access the constructor property .*/i,
+    );
+    await expect(evaluateAsync('a.__proto__', { a: {} })).rejects.toThrow(/Cannot access the __proto__ property .*/i);
+    await expect(evaluateAsync("f['ca' + 'll']", { f: () => 1 })).rejects.toThrow(
+      /Cannot access the call property .*/i,
+    );
+  });
+
+  it('should support computed property access', () => {
+    expect(evaluate('arr[i]', { arr: [10, 20, 30], i: 1 })).toBe(20);
+    expect(evaluate('o[k]', { o: { x: 5 }, k: 'x' })).toBe(5);
+    expect(evaluate('o[k.n]', { o: { x: 5 }, k: { n: 'x' } })).toBe(5);
+    expect(evaluate('o[k()]', { o: { x: 5 }, k: () => 'x' })).toBe(5);
+  });
+
+  it('should not resolve a missing property to a same-named variable', () => {
+    expect(evaluate('a.b', { a: {}, b: 5 })).toBeUndefined();
+  });
+
+  it('should reject member access on null', () => {
+    expect(() => evaluate('a.b', { a: null })).toThrow("TypeError: cannot read properties of null (reading 'b')");
+    expect(() => evaluate('a.b.c', { a: { b: null } })).toThrow(
+      "TypeError: cannot read properties of null (reading 'c')",
+    );
+  });
+
+  it('should short-circuit logical operators', () => {
+    const right = vi.fn(() => true);
+
+    expect(evaluate('a && right()', { a: false, right })).toBe(false);
+    expect(evaluate('a || right()', { a: true, right })).toBe(true);
+    expect(evaluate('a ?? right()', { a: 'set', right })).toBe('set');
+    expect(right).not.toHaveBeenCalled();
+
+    expect(evaluate('a && right()', { a: true, right })).toBe(true);
+    expect(right).toHaveBeenCalledTimes(1);
+
+    // the reason it matters: guarding a member access against a nullish value
+    expect(evaluate('a && a.b', { a: null })).toBeNull();
+    expect(evaluate('a ? a.b : false', { a: null })).toBe(false);
+  });
+
+  it('should support optional chaining', () => {
+    expect(evaluate('a?.b', { a: null })).toBeUndefined();
+    expect(evaluate('a?.b', { a: undefined })).toBeUndefined();
+    expect(evaluate('a?.b', { a: { b: 'value' } })).toBe('value');
+    expect(evaluate('a?.[k]', { a: null, k: 'b' })).toBeUndefined();
+
+    // a short circuit abandons the rest of the chain, not just the one access
+    expect(evaluate('a?.b.c.d', { a: null })).toBeUndefined();
+    expect(evaluate('a?.b()', { a: null })).toBeUndefined();
+    expect(evaluate('a?.b.c()', { a: null })).toBeUndefined();
+
+    // but a genuinely missing property is still an error
+    expect(() => evaluate('a?.b.c', { a: {} })).toThrow("TypeError: cannot read properties of undefined (reading 'c')");
+  });
+
+  it('should support optional calls', () => {
+    const arg = vi.fn(() => 1);
+
+    expect(evaluate('cb?.(arg())', { cb: null, arg })).toBeUndefined();
+    expect(evaluate('o.cb?.(arg())', { o: {}, arg })).toBeUndefined();
+    expect(evaluate('cb?.(arg()).b.c', { cb: undefined, arg })).toBeUndefined();
+
+    // a call that does not happen must not evaluate its arguments
+    expect(arg).not.toHaveBeenCalled();
+
+    expect(evaluate('cb?.(arg())', { cb: (n: number) => n + 1, arg })).toBe(2);
+    expect(arg).toHaveBeenCalledTimes(1);
+
+    // `?.()` only guards against a nullish callee; a non-callable value is still an error
+    expect(() => evaluate('cb?.()', { cb: { notCallable: true } })).toThrow('cb is not a function');
+  });
+
+  it('should allow values that share a name with a forbidden property', () => {
+    expect(evaluate('a', { a: 'constructor' })).toBe('constructor');
+    expect(evaluate("a === 'const' + 'ructor'", { a: 'constructor' })).toBe(true);
+  });
+
   it('should support ternaries', () => {
     expect(evaluate('a ? 1 : 2', { a: true })).toBe(1);
     expect(evaluate('a ? 1 : 2', { a: false })).toBe(2);

package/src/evaluator.ts

@@ -371,11 +371,11 @@ function visitExpression(expression: jsep.Expression, context: EvaluationContext
     case 'ConditionalExpression':
       return visitConditionalExpression(expression as jsep.ConditionalExpression, context);
     case 'CallExpression':
-      return visitCallExpression(expression as jsep.CallExpression, context);
+      return unwrapShortCircuit(visitCallExpression(expression as jsep.CallExpression, context));
     case 'ArrowFunctionExpression':
       return visitArrowFunctionExpression(expression as ArrowExpression, context);
     case 'MemberExpression':
-      return visitMemberExpression(expression as jsep.MemberExpression, context);
+      return unwrapShortCircuit(visitMemberExpression(expression as jsep.MemberExpression, context));
     case 'ArrayExpression':
       return visitArrayExpression(expression as jsep.ArrayExpression, context);
     case 'SequenceExpression':
@@ -426,6 +426,16 @@ function visitUnaryExpression(expression: jsep.UnaryExpression, context: Evaluat
 }
 
 function visitBinaryExpression(expression: jsep.BinaryExpression, context: EvaluationContext) {
+  // these binary operators are meant to short-circuit
+  switch (expression.operator) {
+    case '&&':
+      return visitExpression(expression.left, context) && visitExpression(expression.right, context);
+    case '||':
+      return visitExpression(expression.left, context) || visitExpression(expression.right, context);
+    case '??':
+      return visitExpression(expression.left, context) ?? visitExpression(expression.right, context);
+  }
+
   let left = visitExpression(expression.left, context);
   let right = visitExpression(expression.right, context);
 
@@ -460,12 +470,6 @@ function visitBinaryExpression(expression: jsep.BinaryExpression, context: Evalu
       return left <= right;
     case 'in':
       return left in right;
-    case '&&':
-      return left && right;
-    case '||':
-      return left || right;
-    case '??':
-      return left ?? right;
     default:
       throw `Expression evaluator does not support operator '${expression.operator}' operator`;
   }
@@ -477,8 +481,19 @@ function visitConditionalExpression(expression: jsep.ConditionalExpression, cont
 }
 
 function visitCallExpression(expression: jsep.CallExpression, context: EvaluationContext) {
+  let callee = visitChainOperand(expression.callee, context);
+
+  if (callee === shortCircuit) {
+    return shortCircuit;
+  }
+
+  // `cb?.()` abandons the chain before its arguments are evaluated, so this has to come first; otherwise
+  // an argument's side effects happen for a call that never takes place
+  if (expression.optional && (callee === null || callee === undefined)) {
+    return shortCircuit;
+  }
+
   let args = expression.arguments?.map(handleNullableExpression(context));
-  let callee = visitExpression(expression.callee, context);
 
   if (!callee) {
     throw `No function named ${getCallTargetName(expression.callee)} is defined in this context`;
@@ -516,11 +531,25 @@ function visitArrowFunctionExpression(expression: ArrowExpression, context: Eval
     );
 
     return visitExpression(expression.body, context.addVariables(vars));
-  }.bind(context.thisObj ?? null);
+  }.bind(null);
 }
 
 function visitMemberExpression(expression: jsep.MemberExpression, context: EvaluationContext) {
-  let obj = visitExpression(expression.object, context);
+  const obj = visitChainOperand(expression.object, context);
+
+  if (obj === shortCircuit) {
+    return shortCircuit;
+  }
+
+  if (expression.optional && (obj === null || obj === undefined)) {
+    return shortCircuit;
+  }
+
+  if (obj === null) {
+    throw TypeError(
+      `TypeError: cannot read properties of null (reading '${describePropertyName(expression.property, context)}')`,
+    );
+  }
 
   if (obj === undefined) {
     switch (expression.object.type) {
@@ -529,42 +558,32 @@ function visitMemberExpression(expression: jsep.MemberExpression, context: Evalu
         throw ReferenceError(`ReferenceError: ${objectName} is not defined`);
       }
       case 'MemberExpression': {
-        let propertyName = visitExpressionName(expression.property, context);
-        throw TypeError(`TypeError: cannot read properties of undefined (reading '${propertyName}')`);
+        throw TypeError(
+          `TypeError: cannot read properties of undefined (reading '${describePropertyName(
+            expression.property,
+            context,
+          )}')`,
+        );
       }
       default:
         throw `VisitMemberExpression does not support operator '${expression.object.type}' type`;
     }
   }
 
-  let newObj = obj;
-  if (typeof obj === 'string') {
-    newObj = String.prototype;
-  } else if (typeof obj === 'number') {
-    newObj = Number.prototype;
-  } else if (typeof obj === 'function') {
-    // no-op
-  } else if (typeof obj !== 'object') {
+  if (typeof obj !== 'object' && typeof obj !== 'function' && typeof obj !== 'string' && typeof obj !== 'number') {
     throw `VisitMemberExpression does not support member access on type ${typeof obj}`;
   }
 
-  context.thisObj = newObj;
+  // `a.b` names its property statically; `a[b]` evaluates it, so the result has to be turned into the
+  // exact key the indexer will use before it can be validated
+  const key = expression.computed
+    ? toPropertyKey(visitExpression(expression.property, context))
+    : staticPropertyName(expression.property);
 
-  let result: unknown;
-  switch (expression.property.type) {
-    case 'Identifier':
-    case 'MemberExpression':
-      result = visitExpression(expression.property, context);
-      break;
-    default: {
-      const property = visitExpression(expression.property, context);
-      if (typeof property === 'undefined') {
-        throw { type: 'Illegal property access', message: 'No property was supplied to the property access' };
-      }
-      validatePropertyName(property);
-      result = obj[property];
-    }
-  }
+  validatePropertyName(key);
+  validatePropertyAccess(obj, key);
+
+  const result = obj[key];
 
   if (typeof result === 'function') {
     return result.bind(obj);
@@ -629,19 +648,9 @@ function visitTemplateElement(expression: TemplateElement, context: EvaluationCo
 function visitIdentifier(expression: jsep.Identifier, context: EvaluationContext) {
   validatePropertyName(expression.name);
 
-  // we support both `object` and `function` in the same way as technically property access on functions
-  // is possible; the use-case here is to support JS's "static" functions like `Number.isInteger()`, which
-  // is technically reading a property on a function
-  const thisObj = context.thisObj;
-  if (thisObj && (typeof thisObj === 'object' || typeof thisObj === 'function') && expression.name in thisObj) {
-    const result = thisObj[expression.name];
-    validatePropertyName(result);
-    return result;
-  } else if (context.variables && expression.name in context.variables) {
-    const result = context.variables[expression.name];
-    validatePropertyName(result);
-    return result;
-  } else if (expression.name in context.globals) {
+  if (context.variables && Object.hasOwn(context.variables, expression.name)) {
+    return context.variables[expression.name];
+  } else if (Object.hasOwn(context.globals, expression.name)) {
     return context.globals[expression.name];
   } else {
     return undefined;
@@ -649,14 +658,12 @@ function visitIdentifier(expression: jsep.Identifier, context: EvaluationContext
 }
 
 function visitLiteral(expression: jsep.Literal, context: EvaluationContext) {
-  validatePropertyName(expression.value);
   return expression.value;
 }
 
 // Internal helpers and utilities
 
 interface EvaluationContext {
-  thisObj: object | undefined;
   variables: VariablesMap;
   globals: typeof globals | typeof globalsAsync;
   addVariables(vars: VariablesMap): EvaluationContext;
@@ -672,7 +679,6 @@ function createAsynchronousContext(variables: VariablesMap): EvaluationContext {
 
 function createContextInternal(variables: VariablesMap, globals_: typeof globals | typeof globalsAsync) {
   const context = {
-    thisObj: undefined,
     variables: { ...variables },
     globals: { ...globals_ },
     addVariables(vars: VariablesMap) {
@@ -686,6 +692,35 @@ function createContextInternal(variables: VariablesMap, globals_: typeof globals
   return context;
 }
 
+/**
+ * Marks that an optional link (`a?.b`) found a nullish value. Optional chaining abandons the rest of the
+ * chain rather than just the one access, so this is returned in place of a value and passed along by each
+ * member access and call until it reaches the end of the chain, where {@link unwrapShortCircuit} turns it
+ * into `undefined`. It has to be distinguishable from a real `undefined`, since `a.b.c` where `a.b` is
+ * genuinely undefined is still an error.
+ */
+const shortCircuit = Symbol('optional chain short-circuited');
+
+/**
+ * Visits the object of a member access or the callee of a call, i.e. a link in a chain rather than the end
+ * of one. Dispatching directly keeps a short circuit intact, where {@link visitExpression} would have
+ * already flattened it to `undefined`.
+ */
+function visitChainOperand(expression: jsep.Expression, context: EvaluationContext) {
+  switch (expression.type) {
+    case 'MemberExpression':
+      return visitMemberExpression(expression as jsep.MemberExpression, context);
+    case 'CallExpression':
+      return visitCallExpression(expression as jsep.CallExpression, context);
+    default:
+      return visitExpression(expression, context);
+  }
+}
+
+function unwrapShortCircuit(result: unknown) {
+  return result === shortCircuit ? undefined : result;
+}
+
 // helper useful for handling arrays of expressions, since `null` expressions should not be
 // dispatched to `visitExpression()`
 function handleNullableExpression(context: EvaluationContext) {
@@ -704,6 +739,73 @@ function validatePropertyName(name: unknown) {
   }
 }
 
+/**
+ * Returns the name of a statically-accessed property, i.e. the `b` of `a.b`. jsep only ever parses an
+ * identifier here, so anything else means we were handed an AST we did not build.
+ */
+function staticPropertyName(expression: jsep.Expression) {
+  if (expression.type !== 'Identifier') {
+    throw `VisitMemberExpression does not support a property of type '${expression.type}'`;
+  }
+
+  return (expression as jsep.Identifier).name;
+}
+
+/**
+ * Narrows the result of a computed property expression to the key that `obj[key]` would actually read.
+ * Anything else is refused rather than converted: JS applies ToPropertyKey to whatever it is given, so a
+ * value like `['const' + 'ructor']` reads `constructor` even though it compares equal to nothing.
+ */
+function toPropertyKey(value: unknown): string | number {
+  if (typeof value === 'undefined') {
+    throw { type: 'Illegal property access', message: 'No property was supplied to the property access' };
+  }
+
+  if (typeof value !== 'string' && typeof value !== 'number') {
+    throw {
+      type: 'Illegal property access',
+      message: `Cannot use a value of type ${value === null ? 'null' : typeof value} as a property name`,
+    };
+  }
+
+  return value;
+}
+
+/** Properties of `Object.prototype` that are harmless enough to leave reachable */
+const safeBasePropertyNames = new Set(['toString', 'valueOf', 'hasOwnProperty']);
+
+/**
+ * Refuses any property that resolves on `Object.prototype` or `Function.prototype`.
+ */
+function validatePropertyAccess(obj: object | string | number, key: string | number) {
+  if (safeBasePropertyNames.has(String(key))) {
+    return;
+  }
+
+  // primitives are boxed so that `hasOwn()` sees a string's `length` and indices
+  let holder: object | null = Object(obj);
+  while (holder !== null) {
+    if (Object.hasOwn(holder, key)) {
+      if (holder === Object.prototype || holder === Function.prototype) {
+        throw { type: 'Illegal property access', message: `Cannot access the ${key} property of objects` };
+      }
+
+      return;
+    }
+
+    holder = Object.getPrototypeOf(holder);
+  }
+}
+
+/** Best-effort name for a property, used only to build error messages */
+function describePropertyName(expression: jsep.Expression, context: EvaluationContext) {
+  try {
+    return visitExpressionName(expression, context);
+  } catch {
+    return '<computed>';
+  }
+}
+
 function isValidVariableType(val: unknown): val is VariablesMap['a'] {
   if (
     typeof val === 'string' ||

package/src/extractor.test.ts

@@ -28,6 +28,12 @@ describe('OpenMRS Expression Extractor', () => {
     expect(extractVariableNames('`${a.b}`')).toEqual(['a']);
   });
 
+  it('reports computed property names as variables', () => {
+    expect(extractVariableNames('o[k]')).toEqual(['o', 'k']);
+    expect(extractVariableNames('o["x"]')).toEqual(['o']);
+    expect(extractVariableNames('o.x')).toEqual(['o']);
+  });
+
   it('supports RegExp', () => {
     expect(extractVariableNames('/.*/.test(a)')).toEqual(['a']);
   });

package/src/extractor.ts

@@ -129,6 +129,13 @@ function visitArrowFunctionExpression(expression: ArrowExpression, context: Eval
 
 function visitMemberExpression(expression: jsep.MemberExpression, context: EvaluationContext) {
   visitExpression(expression.object, context);
+
+  // the `b` of `a[b]` is a variable the caller has to supply, whereas the `b` of `a.b` is a property name
+  if (expression.computed) {
+    visitExpression(expression.property, context);
+    return;
+  }
+
   const newContext = { ...context };
   newContext.isLocalExpression = true;
   visitExpression(expression.property, newContext);