feat(ses): ArrayBuffer.p.transferToImmutable

packages/ses/NEWS.md

@@ -27,6 +27,12 @@ User-visible changes in `ses`:
   All use of `Compartment` should migrate to use this option as the standard
   behavior will be enabled by default with the next major version of SES.
 
+- Adds `ArrayBuffer.p.immutable` and `ArrayBuffer.p.transferToImmutable` as a shim for a future proposal. It makes an ArrayBuffer-like object whose contents cannot be mutated. However, due to limitations of the shim
+  - Unlike `ArrayBuffer` and `SharedArrayBuffer` this shim's ArrayBuffer-like object cannot be transfered or cloned between JS threads.
+  - Unlike `ArrayBuffer` and `SharedArrayBuffer`, this shim's ArrayBuffer-like object cannot be used as the backing store of TypeArrays or DataViews.
+  - On Node >= 21 we use the builtin `transferToFixed` to transfer exclusive access to the array buffer contents. On Node <= 20, we emulate `transferToFixedLength` with `structuredClone`. On platforms with neither `transferToFixedLength` nor `structuredClone`, we use `slice` to copy the contents, but have no way to detach the original.
+  - Even after the upcoming `transferToImmutable` proposal is implemented by the platform, the current code will still replace it with the shim implementation, in accord with shim best practices. See https://github.com/endojs/endo/pull/2311#discussion_r1632607527 . It will require a later manual step to delete the shim, after manual analysis of the compat implications.
+
 - Adds support for module descriptors better aligned with XS.
   Compartments use module desriptors to load and link modules.
   The importHook, importNowHook, and moduleMapHook all return module descriptors
@@ -60,7 +66,7 @@ User-visible changes in `ses`:
   in TypeScript),
   the stacktrace line-numbers point back into the original
   source, as they do on Node without SES.
-  
+
 # v1.5.0 (2024-05-06)
 
 - Adds `importNowHook` to the `Compartment` options. The compartment will invoke the hook whenever it encounters a missing dependency while running `compartmentInstance.importNow(specifier)`, which cannot use an asynchronous `importHook`.

packages/ses/src/commons.js

@@ -19,6 +19,7 @@ export { universalThis as globalThis };
 
 export const {
   Array,
+  ArrayBuffer,
   Date,
   FinalizationRegistry,
   Float32Array,
@@ -124,6 +125,7 @@ export const {
 } = Reflect;
 
 export const { isArray, prototype: arrayPrototype } = Array;
+export const { isView, prototype: arrayBufferPrototype } = ArrayBuffer;
 export const { prototype: mapPrototype } = Map;
 export const { revocable: proxyRevocable } = Proxy;
 export const { prototype: regexpPrototype } = RegExp;
@@ -174,6 +176,89 @@ export const arraySome = uncurryThis(arrayPrototype.some);
 export const arraySort = uncurryThis(arrayPrototype.sort);
 export const iterateArray = uncurryThis(arrayPrototype[iteratorSymbol]);
 //
+export const arrayBufferSlice = uncurryThis(arrayBufferPrototype.slice);
+const { asUintN: bigIntAsUintN } = BigInt;
+const { structuredClone } = globalThis;
+export const arrayBufferTransferToFixedLength =
+  // @ts-expect-error absent from Node <= 20 and not yet in TS type
+  // eslint-disable-next-line no-nested-ternary
+  arrayBufferPrototype.transferToFixedLength
+    ? // @ts-expect-error absent from Node <= 20 and not yet in TS type
+      uncurryThis(arrayBufferPrototype.transferToFixedLength)
+    : structuredClone
+      ? /**
+         * @param {ArrayBuffer} arrayBuffer
+         * @param {number} newLength
+         * @returns {ArrayBuffer}
+         */
+        (arrayBuffer, newLength = arrayBuffer.byteLength) => {
+          // There is no `transferToFixedLength` on Node <= 20, but there
+          // is web-standard `structuredClone` on Node >= 17, on all modern
+          // browsers, and on many other JS platforms.
+          // In those cases, we first use `structuredClone` to get a fresh
+          // buffer with exclusive access to the underlying data, while
+          // detaching it from the original `arrayBuffer`.
+
+          newLength = +newLength;
+          bigIntAsUintN(newLength, 0n);
+
+          const newBuffer = /** @type {ArrayBuffer} */ (
+            structuredClone(arrayBuffer, {
+              transfer: [arrayBuffer],
+            })
+          );
+          if (newLength >= newBuffer.byteLength) {
+            return newBuffer;
+          }
+          // If the requested length is shorter than the length of `buffer`,
+          // we use `slice` to shorted the returned result, but at the cost
+          // of an extra copy.
+          //
+          // `slice` accepts negative arguments but `transferToFixedLength`
+          // does not...
+          // get at the underlying ToIndex operation through `BigInt.asUintN`
+          // (avoiding the redundant allocation of e.g. `ArrayBuffer(newLength)`)
+          // and ToNumber through unary `+` (rather than `Number(newLength)`,
+          // which fails to reject BigInts).
+          //
+          // On platforms like Node 20
+          // - without`tranferToFixedLength` or `transfer`
+          // - with `structuredClone`
+          // - with `resize`
+          //
+          // It might seem like we could avoid the extra copy by
+          // `newBuffer.resize(newLength)`. But `structuredClone`
+          // makes ArrayBuffers that are not resizable.
+          return arrayBufferSlice(newBuffer, 0, newLength);
+        }
+      : /**
+         * @param {ArrayBuffer} arrayBuffer
+         * @param {number} newLength
+         * @returns {ArrayBuffer}
+         */
+        (arrayBuffer, newLength = arrayBuffer.byteLength) => {
+          // There is no `transferToFixedLength` on Node <= 20,
+          // and no `structuredClone` on Node <= 17 and possibly on some
+          // non-browser JavaScript platforms.
+          // In those cases,
+          // and assuming the absence of `transfer`, we cannot detach
+          // the original, but we must still produce a new fresh buffer with
+          // exclusive mutability of its underlying state. We use `slice`
+          // both to make this exclusive copy and size it appropriately.
+
+          // `slice` accepts negative arguments but `transferToFixedLength`
+          // does not...
+          // get at the underlying ToIndex operation through `BigInt.asUintN`
+          // (avoiding the redundant allocation of e.g. `ArrayBuffer(newLength)`)
+          // and ToNumber through unary `+` (rather than `Number(newLength)`,
+          // which fails to reject BigInts).
+          newLength = +newLength;
+          bigIntAsUintN(newLength, 0n);
+
+          const newBuffer = arrayBufferSlice(arrayBuffer, 0, newLength);
+          return newBuffer;
+        };
+
 export const mapSet = uncurryThis(mapPrototype.set);
 export const mapGet = uncurryThis(mapPrototype.get);
 export const mapHas = uncurryThis(mapPrototype.has);

packages/ses/src/get-anonymous-intrinsics.js

@@ -14,6 +14,7 @@ import {
   matchAllSymbol,
   regexpPrototype,
   globalThis,
+  ArrayBuffer,
 } from './commons.js';
 import { InertCompartment } from './compartment.js';
 
@@ -157,5 +158,15 @@ export const getAnonymousIntrinsics = () => {
     );
   }
 
+  const ab = new ArrayBuffer(0);
+  // @ts-expect-error TODO How do I add transferToImmutable to ArrayBuffer type?
+  // eslint-disable-next-line @endo/no-polymorphic-call
+  const iab = ab.transferToImmutable();
+  const iabProto = getPrototypeOf(iab);
+  if (iabProto !== ArrayBuffer.prototype) {
+    // In a native implementation, these will be the same prototype
+    intrinsics['%ImmutableArrayBufferPrototype%'] = iabProto;
+  }
+
   return intrinsics;
 };

packages/ses/src/immutable-array-buffer-shim.js

@@ -0,0 +1,115 @@
+import {
+  setPrototypeOf,
+  defineProperties,
+  arrayBufferSlice,
+  arrayBufferTransferToFixedLength,
+  arrayBufferPrototype,
+  getOwnPropertyDescriptors,
+  TypeError,
+} from './commons.js';
+
+if ('transferToImmutable' in arrayBufferPrototype) {
+  // If `transferToImmutable` already exists, it may be because the platform
+  // has implemented the proposal this shim emulates.
+  // See https://github.com/endojs/endo/pull/2311#discussion_r1632607527
+  // Conditional shims for non stage 4 features have been seen as problematic by
+  // the community as there is a risk that the program would start relying on a
+  // shim behavior that does not match what the final spec says, resulting in
+  // breakage when the engine starts implementing the feature.
+  // eslint-disable-next-line @endo/no-polymorphic-call
+  console.warn('Overriding existing transferToImmutable with shim');
+}
+
+/**
+ * This class only exists within the shim, as a convience for imperfectly
+ * emulating the proposal, which would not have this class. In the proposal,
+ * `transferToImmutable` makes a new `ArrayBuffer` that inherits from
+ * `ArrayBuffer.prototype` as you'd expect. In the shim, `transferToImmutable`
+ * makes a normal object that inherits from
+ * `ImmutableArrayBufferInternal.prototype`, which has been surgically
+ * altered to inherit from `ArrayBuffer.prototype`. The constructor is
+ * captured for use internal to this module, and is made otherwise inaccessible.
+ * Therefore, `ImmutableArrayBufferInternal.prototype` and all its methods
+ * and accessor functions effectively become hidden intrinsics.
+ *
+ * TODO handle them as hidden intrinsics, so they get hardened when they should.
+ */
+class ImmutableArrayBufferInternal {
+  /** @type {ArrayBuffer} */
+  #buffer;
+
+  constructor(buffer) {
+    // This also enforces that `buffer` is a genuine `ArrayBuffer`.
+    // This constructor is deleted from the prototype below.
+    this.#buffer = arrayBufferSlice(buffer, 0);
+  }
+
+  get byteLength() {
+    return this.#buffer.byteLength;
+  }
+
+  get detached() {
+    this.#buffer; // shim brand check
+    return false;
+  }
+
+  get maxByteLength() {
+    // Not underlying maxByteLength, which is irrelevant
+    return this.#buffer.byteLength;
+  }
+
+  get resizable() {
+    this.#buffer; // shim brand check
+    return false;
+  }
+
+  get immutable() {
+    this.#buffer; // shim brand check
+    return true;
+  }
+
+  slice(begin = 0, end = undefined) {
+    return arrayBufferSlice(this.#buffer, begin, end);
+  }
+
+  resize(_newByteLength = undefined) {
+    this.#buffer; // shim brand check
+    throw TypeError('Cannot resize an immutable ArrayBuffer');
+  }
+
+  transfer(_newLength = undefined) {
+    this.#buffer; // shim brand check
+    throw TypeError('Cannot detach an immutable ArrayBuffer');
+  }
+
+  transferToFixedLength(_newLength = undefined) {
+    this.#buffer; // shim brand check
+    throw TypeError('Cannot detach an immutable ArrayBuffer');
+  }
+
+  transferToImmutable(_newLength = undefined) {
+    this.#buffer; // shim brand check
+    throw TypeError('Cannot detach an immutable ArrayBuffer');
+  }
+}
+
+const ImmutableArrayBufferInternalPrototype =
+  ImmutableArrayBufferInternal.prototype;
+// @ts-expect-error can only delete optionals
+delete ImmutableArrayBufferInternalPrototype.constructor;
+
+setPrototypeOf(ImmutableArrayBufferInternalPrototype, arrayBufferPrototype);
+
+defineProperties(
+  arrayBufferPrototype,
+  getOwnPropertyDescriptors({
+    get immutable() {
+      return false;
+    },
+    transferToImmutable(newLength = undefined) {
+      return new ImmutableArrayBufferInternal(
+        arrayBufferTransferToFixedLength(this, newLength),
+      );
+    },
+  }),
+);

packages/ses/src/lockdown.js

@@ -55,6 +55,7 @@ import { makeCompartmentConstructor } from './compartment.js';
 import { tameHarden } from './tame-harden.js';
 import { tameSymbolConstructor } from './tame-symbol-constructor.js';
 import { tameFauxDataProperties } from './tame-faux-data-properties.js';
+import './immutable-array-buffer-shim.js';
 
 /** @import {LockdownOptions} from '../types.js' */
 

packages/ses/src/permits.js

@@ -1283,6 +1283,31 @@ export const permitted = {
     // https://github.com/tc39/proposal-arraybuffer-transfer
     transferToFixedLength: fn,
     detached: getter,
+    // https://github.com/endojs/endo/pull/2309#issuecomment-2155513240
+    // to be proposed
+    transferToImmutable: fn,
+    immutable: getter,
+  },
+
+  // If this exists, it is purely an artifact of how we currently shim
+  // `transferToImmutable`. As natively implemented, there would be no
+  // such extra prototype.
+  '%ImmutableArrayBufferPrototype%': {
+    '[[Proto]]': '%ArrayBufferPrototype%',
+    byteLength: getter,
+    slice: fn,
+    // See https://github.com/tc39/proposal-resizablearraybuffer
+    transfer: fn,
+    resize: fn,
+    resizable: getter,
+    maxByteLength: getter,
+    // https://github.com/tc39/proposal-arraybuffer-transfer
+    transferToFixedLength: fn,
+    detached: getter,
+    // https://github.com/endojs/endo/pull/2309#issuecomment-2155513240
+    // to be proposed
+    transferToImmutable: fn,
+    immutable: getter,
   },
 
   // SharedArrayBuffer Objects

packages/ses/test/immutable-array-buffer.test.js

@@ -0,0 +1,91 @@
+import test from 'ava';
+import '../index.js';
+
+const { isFrozen, getPrototypeOf } = Object;
+
+lockdown();
+
+test('Immutable ArrayBuffer installed and hardened', t => {
+  const ab1 = new ArrayBuffer(0);
+  const iab = ab1.transferToImmutable();
+  const iabProto = getPrototypeOf(iab);
+  t.true(isFrozen(iabProto));
+  t.true(isFrozen(iabProto.slice));
+});
+
+test('Immutable ArrayBuffer ops', t => {
+  // Absent on Node <= 18
+  const canResize = 'maxByteLength' in ArrayBuffer.prototype;
+
+  const ab1 = new ArrayBuffer(2, { maxByteLength: 7 });
+  const ta1 = new Uint8Array(ab1);
+  ta1[0] = 3;
+  ta1[1] = 4;
+  const iab = ab1.transferToImmutable();
+  t.true(iab instanceof ArrayBuffer);
+  ta1[1] = 5;
+  const ab2 = iab.slice(0);
+  const ta2 = new Uint8Array(ab2);
+  t.is(ta1[1], undefined);
+  t.is(ta2[1], 4);
+  ta2[1] = 6;
+
+  const ab3 = iab.slice(0);
+  t.true(ab3 instanceof ArrayBuffer);
+
+  const ta3 = new Uint8Array(ab3);
+  t.is(ta1[1], undefined);
+  t.is(ta2[1], 6);
+  t.is(ta3[1], 4);
+
+  t.is(ab1.byteLength, 0);
+  t.is(iab.byteLength, 2);
+  t.is(ab2.byteLength, 2);
+
+  t.is(iab.maxByteLength, 2);
+  if (canResize) {
+    t.is(ab1.maxByteLength, 0);
+    t.is(ab2.maxByteLength, 2);
+  }
+
+  if ('detached' in ab1) {
+    t.true(ab1.detached);
+    t.false(ab2.detached);
+    t.false(ab3.detached);
+  }
+  t.false(iab.detached);
+  t.false(iab.resizable);
+});
+
+// This could have been written as a test.failing as compared to
+// the immutable ArrayBuffer we'll propose. However, I'd rather test what
+// the shim purposely does instead.
+test('Immutable ArrayBuffer shim limitations', t => {
+  const ab1 = new ArrayBuffer(2);
+  const dv1 = new DataView(ab1);
+  t.is(dv1.buffer, ab1);
+  t.is(dv1.byteLength, 2);
+  const ta1 = new Uint8Array(ab1);
+  ta1[0] = 3;
+  ta1[1] = 4;
+  t.is(ta1.byteLength, 2);
+
+  t.throws(() => new DataView({}), { instanceOf: TypeError });
+  // Unfortutanely, calling a TypeArray constructor with an object that
+  // is not a TypeArray, ArrayBuffer, or Iterable just creates a useless
+  // empty TypedArray, rather than throwing.
+  const ta2 = new Uint8Array({});
+  t.is(ta2.byteLength, 0);
+
+  const iab = ab1.transferToImmutable();
+  t.throws(() => new DataView(iab), {
+    instanceOf: TypeError,
+  });
+  // Unfortunately, unlike the immutable ArrayBuffer to be proposed,
+  // calling a TypedArray constructor with the shim implementation of
+  // an immutable ArrayBuffer as argument treats it as an unrecognized object,
+  // rather than throwing an error.
+  t.is(iab.byteLength, 2);
+  const ta3 = new Uint8Array(iab);
+  t.is(ta3.byteLength, 0);
+});