Background

JavaScript object properties are public by default.

Since ECMAScript (ES) 2020, there is native support for private properties (and methods) using the hash (#) prefix.

In my previous post, I demonstrate a way to implement natively-enforced (not based on the underscore (_) convention) protected-style properties that doesn’t require shared lexical scope or public accessors (i.e. it behaves very much like you would expect a native implementation to).

The historical way to simulate protected properties was to use a lexically-scoped WeakMap of instances to properties (or, more efficiently, to a protected-state object).

The way protected properties work, all sub-classes automatically get access to all protected properties of the current object instance. A method also gains access to other object instances if the other instance is at least as derived in the same class hierarchy (i.e. a method defined in class C has access to other instances if they are instanceof C).

The “legacy” lexically-scoped WeakMap approach is more like trusted-class access. A method at any class level can access any type of instance stored in the WeakMap, even it’s a less-or-differently-derived instance.

What if you want the trusted-class capability, but without the lexically-shared-scope limitation (having to have classes appear within the same source file in order to share data)?

Enter “insider” properties.

“Insider” Properties

The insider-properties model allows you to share private state objects across trusted classes. The effect is similar to sharing access to a WeakMap, but classes can be in separate files without publicly-usable accessors for access distribution.

This model has three types of components:

1. A trust component, which defines the scope of trust
2. A base-class component, which creates the shared state and controls distribution
3. One or more sub-class components, which request and cache access to the shared state

The Trust Component

The trust component is a stand-alone file that contains the “trust configuration”. It is also a JavaScript “barrel file” that exports the related base and trusted sub-classes.

This approach groups trusted classes in a way that can be deployment/application-specific without modifying the class files themselves in any way in addition to insuring trusted-version consistency and proper dependency-loading resolution.

Here is the trust-component pattern:

// "Barrel" bundling of base + trusted sub-classes
import { Base } from './insider-base.js';
import { Sub } from './insider-sub.js';
export { Base, Sub };

let trusted;

// Return the trusted sub-class list
// (but not before the classes are initialized)
export const getTrusted = () => {
    // Adjust the trusted-class array below as required
    trusted ||= Object.freeze([Sub]);
    return trusted;
};

Base-Class Component

In addition to your core base-class behavior, the base class is also responsible for creating the initial, per-instance #insider state object and controlling distribution of access to trusted sub-classes (which will store a reference to the same shared object in their own #insider private fields).

Here is the base-component pattern:

import { getTrusted } from './insider-trusted.js';

export const Base = (() => {
    const cls = Object.freeze(class Base {
        static #trusted; // Base-class cached trusted-sub-class array
        static #insiderBaton = null; // Per-class handoff baton
        #insider = { /* insider: true /* Instance insider properties */ };

        // Base-class constructor
        constructor () {
            // Cache trusted sub-class list upon first instantiation
            cls.#trusted ||= getTrusted();
            // Insider instance properties (this.#insider.prop) are ready here
        }

        /*
         * Base-class-only class-method to pass #insider access
         * @param {Class} reqCls - The requesting method's class (for proper handoff)
         * @param {Object} instance - The instance whose #insider is requested
         * @param {Function} receiver - Baton-receiver/instance-#insider-setter function
         */
        static _getInsider (reqCls, instance, receiver) {
            // Request must be for a class on the trusted list
            if (!cls.#trusted.includes(reqCls)) throw new Error('Untrusted request');
            // Make sure the handoff class-method is a frozen function
            const passProps = Object.getOwnPropertyDescriptor(reqCls, '_passInsider');
            if (typeof passProps.value !== 'function' || passProps.writable !== false || passProps.configurable !== false) throw new Error('Unsafe handoff');
            // Use the supplied class-level handoff method to pass #insider to the receiver
            reqCls._passInsider(instance.#insider, receiver);
        }
    });
    Object.freeze(cls.prototype);
    return cls;
})();

Sub-Class Components

Sub-class constructors are responsible for requesting insider property access and caching it in its private #insider field for use within each sub-class level.

They do this by calling a known, frozen, class-method of a known class (the base class), passing it their class object, the instance for which #insider properties are desired, and a “baton receiver function”.

The base class passes the #insider state object and the supplied receiver function to a known, frozen, “handoff” class-method of the specified class. The handoff function uses a class-specific baton (every trusted sub-class must have one), which the receiver function (as an instance method of the same class) is able to receive.

The #insider state of other instances can be received using the same mechanism, but by supplying an instance other than this and a receiver function that sets something other than this.#insider (typically a variable in the requesting method’s local scope).

The sub-class pattern looks like this:

 import { Base } from './insider-trusted.js';

 export const Sub = (() => {
    const cls = Object.freeze(class Sub extends Base {
        static #insiderBaton = null; // Handoff baton (in every sub-class)
        #insider; // Per-class-level private view of shared #insider state

        constructor () {
            super();
            Base._getInsider(cls, this, () => this.#insider = cls.#insiderBaton);
            // Insider instance properties (this.#insider.prop) are ready here
        }

        /*
         * Baton handoff function (all sub-classes); called by Base._getInsider
         * @param {Object} insider - The requested instances #insider
         * @param {Function} receiver - The receiver function to call
         */
        static _passInsider (insider, receiver) {
            cls.#insiderBaton = insider;
            receiver(); // Receiver must be a cls method to accept the baton
            cls.#insiderBaton = null;
        }
    });
    Object.freeze(cls.prototype);
    return cls;
})();

Accessing Another Instance’s #insider

There are two ways to access another instance’s #insider.

The first method uses native JavaScript cross-instance, direct private-field access (e.g. otherInstance.#insider). This only works if the other instance is at least as derived as the accessing method’s class, in the same class hierarchy. This will always work from base-class methods, since trusted sub-classes are derived from the base class.

The second method uses Base._getInsider with a custom receiver function. Since it’s invoking a base-class method, it can be used between any instances (as long as the requesting method is in one of the trusted sub-classes).

        // Two ways to get another instance's #insider
        #getOtherInsider (other) {
            // #1: Only works if other instanceof cls (at least as derived in same hierarchy)
            // Should always work from Base
            const insider1 = other.#insider;
            // return insider1;

            // #2: Works for any instance (if called from a trusted-sub-class method)
            let insider2;
            Base._getInsider(cls, other, () => insider2 = cls.#insiderBaton);
            // return insider2;
        }

Security

Most forms of type checking in JavaScript, including those based on an object’s constructor or new.target can be misdirected through code manipulation. Private element (#) access is managed directly at the JavaScript-engine level, however, and therefore does not have that problem. This model leverages that mechanism for verifying that only methods of actually-trusted classes can gain access.

Base._getInsider will only ever pass #insider via a pre-determined method on a class it is configured to trust. A method in an untrusted class has two options:

1. Follow the pattern, creating its own handoff function and supplying its own class to Base._getInsider
2. “Lie”, passing a trusted class to Base._getInsider instead

In the first case, the class will not be on the trusted list, so Base._getInsider will throw an error without even attempting to distribute access. This result will be typical for trust misconfiguration (a sub-class that should be trusted wasn’t added to the trust configuration, or the wrong trust configuration is being loaded).

In the second case, Base._getInsider will distribute #insider access to the specified (trusted class) baton, but the requesting method, being of a different class, will have no access to the trusted-class baton. This might happen as the result of malicious code, or if “hard-wired” class names are being used instead of the boilerplate approach in the pattern as documented.

The patterns here include code to freeze class and prototype objects. This is largely performative (only protecting against some types of coding mistakes, as opposed to actual attacks), however, unless you own the execution context and can ensure that Object.freeze(Object) is run before any untrusted code executes.

Resources

The code is also available on GitHub at https://github.com/bkatzung/insider-js.

Related

Implementing Cross-File JavaScript Protected Properties And Methods