circuitjson-toolkit 1.4.1 → 1.4.3

package/src/core/worker/NativeParserWorkerTransport.mjs

@@ -0,0 +1,201 @@
+import { TOOLKIT_WORKER_PROTOCOL } from './ToolkitWorkerProtocol.mjs'
+
+const REFLECT_APPLY = Reflect.apply
+const REFLECT_CONSTRUCT = Reflect.construct
+const REFLECT_OWN_KEYS = Reflect.ownKeys
+const GET_PROTOTYPE = Object.getPrototypeOf
+const GET_DESCRIPTORS = Object.getOwnPropertyDescriptors
+const HAS_OWN = Object.hasOwn
+const OBJECT_PROTOTYPE = Object.prototype
+const WEAK_MAP_GET = WeakMap.prototype.get
+const WEAK_MAP_SET = WeakMap.prototype.set
+const WEAK_MAP_DELETE = WeakMap.prototype.delete
+const WORKER_CONSTRUCTOR = globalThis.Worker
+const WORKER_POST = WORKER_CONSTRUCTOR?.prototype?.postMessage
+const WORKER_TERMINATE = WORKER_CONSTRUCTOR?.prototype?.terminate
+const ADD_EVENT_LISTENER = EventTarget.prototype.addEventListener
+const REMOVE_EVENT_LISTENER = EventTarget.prototype.removeEventListener
+const MESSAGE_DATA = Object.getOwnPropertyDescriptor(
+    MessageEvent.prototype,
+    'data'
+)?.get
+const EVENT_CURRENT_TARGET = Object.getOwnPropertyDescriptor(
+    Event.prototype,
+    'currentTarget'
+)?.get
+const EVENT_TRUSTED =
+    Object.getOwnPropertyDescriptor(new Event('message'), 'isTrusted')?.get ||
+    Object.getOwnPropertyDescriptor(Event.prototype, 'isTrusted')?.get
+const ERROR_DATA =
+    typeof ErrorEvent === 'function'
+        ? Object.getOwnPropertyDescriptor(ErrorEvent.prototype, 'error')?.get
+        : null
+const RECEIVED_RESULTS = new WeakMap()
+
+/**
+ * Keeps native workers and their unexposed structured-clone results private.
+ * A custom factory cannot mint the one-use result capabilities created here.
+ */
+export class NativeParserWorkerTransport {
+    #worker
+    #listeners = new Map()
+    #nativeListeners = new Map()
+
+    /**
+     * Constructs an isolated transport using the captured native constructor.
+     * @param {string | URL} url Worker module URL.
+     */
+    constructor(url) {
+        this.#worker = REFLECT_CONSTRUCT(WORKER_CONSTRUCTOR, [
+            url,
+            { type: 'module' }
+        ])
+        for (const type of ['message', 'error', 'messageerror']) {
+            const listener = (event) => this.#receive(type, event)
+            this.#nativeListeners.set(type, listener)
+            REFLECT_APPLY(ADD_EVENT_LISTENER, this.#worker, [type, listener])
+        }
+    }
+
+    /**
+     * Uses private native transport only while the captured host is unchanged.
+     * Replaced or emulated Worker constructors retain generic validation.
+     * @param {string | URL} url Worker module URL.
+     * @returns {object} Browser-compatible worker transport.
+     */
+    static create(url) {
+        const Constructor = globalThis.Worker
+        if (
+            Constructor !== WORKER_CONSTRUCTOR ||
+            typeof WORKER_POST !== 'function' ||
+            typeof WORKER_TERMINATE !== 'function' ||
+            !MESSAGE_DATA ||
+            !EVENT_CURRENT_TARGET ||
+            !EVENT_TRUSTED
+        ) {
+            return REFLECT_CONSTRUCT(Constructor, [url, { type: 'module' }])
+        }
+        return new NativeParserWorkerTransport(url)
+    }
+
+    /**
+     * Consumes an opaque result exactly once. The returned data has never been
+     * exposed outside this transport; exposing it here destroys its capability.
+     * @param {unknown} token Result candidate.
+     * @returns {{ value: unknown } | null} Privately received data, if proven.
+     */
+    static consumeResult(token) {
+        const received = REFLECT_APPLY(WEAK_MAP_GET, RECEIVED_RESULTS, [token])
+        if (!received) return null
+        REFLECT_APPLY(WEAK_MAP_DELETE, RECEIVED_RESULTS, [token])
+        return received
+    }
+
+    /** @param {string} type Event type. @param {Function} listener Listener. @returns {void} */
+    addEventListener(type, listener) {
+        if (!this.#listeners.has(type)) this.#listeners.set(type, new Set())
+        this.#listeners.get(type).add(listener)
+    }
+
+    /** @param {string} type Event type. @param {Function} listener Listener. @returns {void} */
+    removeEventListener(type, listener) {
+        this.#listeners.get(type)?.delete(listener)
+    }
+
+    /** @param {unknown} message Request. @param {Transferable[]} [transfer] Transfer list. @returns {void} */
+    postMessage(message, transfer = []) {
+        REFLECT_APPLY(WORKER_POST, this.#worker, [message, transfer])
+    }
+
+    /** Detaches native listeners and terminates the private worker. @returns {void} */
+    terminate() {
+        for (const [type, listener] of this.#nativeListeners) {
+            REFLECT_APPLY(REMOVE_EVENT_LISTENER, this.#worker, [type, listener])
+        }
+        this.#nativeListeners.clear()
+        this.#listeners.clear()
+        REFLECT_APPLY(WORKER_TERMINATE, this.#worker, [])
+    }
+
+    /**
+     * Hides the native target and result graph before invoking any consumer.
+     * Synthetic events and invalid envelopes never receive a capability.
+     * @param {string} type Event type.
+     * @param {Event} event Native event.
+     * @returns {void}
+     */
+    #receive(type, event) {
+        let forwarded = {}
+        if (type === 'message') {
+            const data = REFLECT_APPLY(MESSAGE_DATA, event, [])
+            forwarded = { data }
+            if (
+                REFLECT_APPLY(EVENT_TRUSTED, event, []) === true &&
+                REFLECT_APPLY(EVENT_CURRENT_TARGET, event, []) === this.#worker
+            ) {
+                try {
+                    const message =
+                        NativeParserWorkerTransport.#resultMessage(data)
+                    if (message) {
+                        const token = Object.freeze(Object.create(null))
+                        REFLECT_APPLY(WEAK_MAP_SET, RECEIVED_RESULTS, [
+                            token,
+                            { value: message.value }
+                        ])
+                        message.value = token
+                        forwarded = { data: message }
+                    }
+                } catch {
+                    // The ordinary client boundary reports malformed envelopes.
+                }
+            }
+        } else if (type === 'error') {
+            forwarded = {
+                error: ERROR_DATA ? REFLECT_APPLY(ERROR_DATA, event, []) : null
+            }
+        }
+        for (const listener of this.#listeners.get(type) || []) {
+            REFLECT_APPLY(listener, undefined, [forwarded])
+        }
+    }
+
+    /**
+     * Captures only exact native result headers without calling replaceable
+     * exported helpers that could introduce caller-owned values into the graph.
+     * @param {unknown} data Privately received native event data.
+     * @returns {object | null} Result envelope safe to hide behind a capability.
+     */
+    static #resultMessage(data) {
+        if (!data || typeof data !== 'object') return null
+        const prototype = GET_PROTOTYPE(data)
+        if (prototype !== OBJECT_PROTOTYPE && prototype !== null) return null
+        const descriptors = GET_DESCRIPTORS(data)
+        if (REFLECT_OWN_KEYS(descriptors).length !== 4) return null
+        for (const key of ['protocol', 'type', 'requestId', 'value']) {
+            const descriptor = descriptors[key]
+            if (
+                !descriptor ||
+                !HAS_OWN(descriptor, 'value') ||
+                descriptor.enumerable !== true
+            ) {
+                return null
+            }
+        }
+        const protocol = descriptors.protocol.value
+        const type = descriptors.type.value
+        const requestId = descriptors.requestId.value
+        if (
+            protocol !== TOOLKIT_WORKER_PROTOCOL ||
+            type !== 'result' ||
+            typeof requestId !== 'string' ||
+            !requestId ||
+            requestId.length > 256
+        ) {
+            return null
+        }
+        return { protocol, type, requestId, value: descriptors.value.value }
+    }
+}
+
+Object.freeze(NativeParserWorkerTransport.prototype)
+Object.freeze(NativeParserWorkerTransport)

package/src/core/worker/ParserWorkerClient.mjs

@@ -3,6 +3,7 @@ import { RuntimeProxyBoundary } from '../contracts/RuntimeProxyBoundary.mjs'
 import { TOOLKIT_WORKER_PROTOCOL } from './ToolkitWorkerProtocol.mjs'
 import { WorkerRequestData } from './WorkerRequestData.mjs'
 import { WorkerResponseData } from './WorkerResponseData.mjs'
+import { NativeParserWorkerTransport } from './NativeParserWorkerTransport.mjs'
 
 const ABORTED_GETTER = Object.getOwnPropertyDescriptor(
     AbortSignal.prototype,
@@ -73,14 +74,22 @@ export class ParserWorkerClient {
         }
     }
 
-    /**
-     * Returns the process-local default client, creating it lazily.
-     * @returns {ParserWorkerClient} Default worker client.
-     */
+    /** @returns {ParserWorkerClient} Lazily-created process-local default client. */
     static defaultClient() {
         return ParserWorkerClient.#defaultClientFor(null)
     }
 
+    /**
+     * Creates a client whose native worker and received graphs remain private.
+     * @param {string | URL} workerUrl Worker module URL.
+     * @returns {ParserWorkerClient} Client using native clone provenance.
+     */
+    static fromWorkerUrl(workerUrl) {
+        return new ParserWorkerClient({
+            createWorker: () => NativeParserWorkerTransport.create(workerUrl)
+        })
+    }
+
     /**
      * Returns the process-local default client for one internal attempt.
      * @param {object | null} attemptToken Internal attempt identity.
@@ -91,26 +100,15 @@ export class ParserWorkerClient {
             throw ParserWorkerClient.#unavailableError(attemptToken)
         }
         if (!ParserWorkerClient.#defaultClient) {
-            ParserWorkerClient.#defaultClient = new ParserWorkerClient({
-                createWorker: () => {
-                    const WorkerConstructor = globalThis.Worker
-                    return Reflect.construct(WorkerConstructor, [
-                        new URL(
-                            '../../workers/parser.worker.mjs',
-                            import.meta.url
-                        ),
-                        { type: 'module' }
-                    ])
-                }
-            })
+            ParserWorkerClient.#defaultClient =
+                ParserWorkerClient.fromWorkerUrl(
+                    new URL('../../workers/parser.worker.mjs', import.meta.url)
+                )
         }
         return ParserWorkerClient.#defaultClient
     }
 
-    /**
-     * Disposes the process-local default worker client when one exists.
-     * @returns {void}
-     */
+    /** Disposes the process-local default worker client. @returns {void} */
     static disposeDefault() {
         ParserWorkerClient.#defaultClient?.dispose()
         ParserWorkerClient.#defaultClient = null

package/src/core/worker/WorkerBinaryData.mjs

@@ -0,0 +1,201 @@
+const ARRAY_BUFFER_BYTE_LENGTH_GETTER = Object.getOwnPropertyDescriptor(
+    ArrayBuffer.prototype,
+    'byteLength'
+)?.get
+const ARRAY_BUFFER_RESIZABLE_GETTER = Object.getOwnPropertyDescriptor(
+    ArrayBuffer.prototype,
+    'resizable'
+)?.get
+const SHARED_ARRAY_BUFFER_BYTE_LENGTH_GETTER =
+    typeof SharedArrayBuffer === 'function'
+        ? Object.getOwnPropertyDescriptor(
+              SharedArrayBuffer.prototype,
+              'byteLength'
+          )?.get
+        : null
+const TYPED_ARRAY_PROTOTYPE = Object.getPrototypeOf(Uint8Array.prototype)
+const TYPED_ARRAY_BUFFER_GETTER = Object.getOwnPropertyDescriptor(
+    TYPED_ARRAY_PROTOTYPE,
+    'buffer'
+)?.get
+const TYPED_ARRAY_BYTE_LENGTH_GETTER = Object.getOwnPropertyDescriptor(
+    TYPED_ARRAY_PROTOTYPE,
+    'byteLength'
+)?.get
+const TYPED_ARRAY_BYTE_OFFSET_GETTER = Object.getOwnPropertyDescriptor(
+    TYPED_ARRAY_PROTOTYPE,
+    'byteOffset'
+)?.get
+const TYPED_ARRAY_TAG_GETTER = Object.getOwnPropertyDescriptor(
+    TYPED_ARRAY_PROTOTYPE,
+    Symbol.toStringTag
+)?.get
+const DATA_VIEW_BUFFER_GETTER = Object.getOwnPropertyDescriptor(
+    DataView.prototype,
+    'buffer'
+)?.get
+const DATA_VIEW_BYTE_LENGTH_GETTER = Object.getOwnPropertyDescriptor(
+    DataView.prototype,
+    'byteLength'
+)?.get
+const DATA_VIEW_BYTE_OFFSET_GETTER = Object.getOwnPropertyDescriptor(
+    DataView.prototype,
+    'byteOffset'
+)?.get
+const DATA_VIEW_CONSTRUCTOR = DataView
+const UINT8_ARRAY_CONSTRUCTOR = Uint8Array
+const UINT8_ARRAY_SET = Uint8Array.prototype.set
+const ARRAY_BUFFER_IS_VIEW = ArrayBuffer.isView
+const OBJECT_GET_PROTOTYPE_OF = Object.getPrototypeOf
+const OBJECT_PROTOTYPE = Object.prototype
+const TYPED_ARRAYS = new Map(
+    [
+        Int8Array,
+        Uint8Array,
+        Uint8ClampedArray,
+        Int16Array,
+        Uint16Array,
+        Int32Array,
+        Uint32Array,
+        Float32Array,
+        Float64Array,
+        typeof BigInt64Array === 'function' ? BigInt64Array : null,
+        typeof BigUint64Array === 'function' ? BigUint64Array : null
+    ]
+        .filter(Boolean)
+        .map((Constructor) => [Constructor.name, Constructor])
+)
+
+/**
+ * Inspects and isolates worker binary data through captured intrinsic slots.
+ */
+export class WorkerBinaryData {
+    /**
+     * Classifies records only in a privately received native clone graph.
+     * Generic inputs must still use exact brands, even with these prototypes.
+     * @param {object} value Proven native-clone value.
+     * @returns {boolean} Whether it has a normalized plain-record prototype.
+     */
+    static isStandardRecord(value) {
+        const prototype = OBJECT_GET_PROTOTYPE_OF(value)
+        return prototype === OBJECT_PROTOTYPE || prototype === null
+    }
+
+    /**
+     * Recreates one intrinsic view on an exact isolated backing buffer.
+     * @param {{ byteLength: number, tag: string }} view View fields.
+     * @param {ArrayBuffer} buffer Exact copied buffer.
+     * @returns {ArrayBufferView} Recreated view.
+     */
+    static recreateView(view, buffer) {
+        if (view.tag === 'DataView') return new DATA_VIEW_CONSTRUCTOR(buffer)
+        const Constructor = TYPED_ARRAYS.get(view.tag)
+        if (!Constructor || view.byteLength % Constructor.BYTES_PER_ELEMENT) {
+            throw new TypeError('Worker request binary view is unsupported.')
+        }
+        return new Constructor(
+            buffer,
+            0,
+            view.byteLength / Constructor.BYTES_PER_ELEMENT
+        )
+    }
+
+    /**
+     * Reads genuine typed-array or DataView internal slots.
+     * @param {unknown} value View candidate.
+     * @returns {{ buffer: ArrayBufferLike, byteOffset: number, byteLength: number, tag: string } | null} Intrinsic view fields.
+     */
+    static view(value) {
+        if (!ARRAY_BUFFER_IS_VIEW(value)) return null
+        try {
+            const tag = TYPED_ARRAY_TAG_GETTER?.call(value)
+            if (TYPED_ARRAYS.has(tag)) {
+                return {
+                    buffer: TYPED_ARRAY_BUFFER_GETTER.call(value),
+                    byteOffset: TYPED_ARRAY_BYTE_OFFSET_GETTER.call(value),
+                    byteLength: TYPED_ARRAY_BYTE_LENGTH_GETTER.call(value),
+                    tag
+                }
+            }
+            if (
+                DATA_VIEW_BUFFER_GETTER &&
+                DATA_VIEW_BYTE_OFFSET_GETTER &&
+                DATA_VIEW_BYTE_LENGTH_GETTER
+            ) {
+                const buffer = DATA_VIEW_BUFFER_GETTER.call(value)
+                return {
+                    buffer,
+                    byteOffset: DATA_VIEW_BYTE_OFFSET_GETTER.call(value),
+                    byteLength: DATA_VIEW_BYTE_LENGTH_GETTER.call(value),
+                    tag: 'DataView'
+                }
+            }
+        } catch {
+            return null
+        }
+        return null
+    }
+
+    /** @param {unknown} value Candidate. @returns {number | null} Byte length. */
+    static bufferLength(value) {
+        if (!ARRAY_BUFFER_BYTE_LENGTH_GETTER) return null
+        try {
+            return ARRAY_BUFFER_BYTE_LENGTH_GETTER.call(value)
+        } catch {
+            return null
+        }
+    }
+
+    /** @param {unknown} value Candidate. @returns {number | null} Byte length. */
+    static sharedBufferLength(value) {
+        if (!SHARED_ARRAY_BUFFER_BYTE_LENGTH_GETTER) return null
+        try {
+            return SHARED_ARRAY_BUFFER_BYTE_LENGTH_GETTER.call(value)
+        } catch {
+            return null
+        }
+    }
+
+    /**
+     * Returns whether a genuine ArrayBuffer can change size after accounting.
+     * @param {unknown} value Buffer candidate.
+     * @returns {boolean} Whether the buffer is resizable.
+     */
+    static isResizableBuffer(value) {
+        if (!ARRAY_BUFFER_RESIZABLE_GETTER) return false
+        try {
+            return ARRAY_BUFFER_RESIZABLE_GETTER.call(value) === true
+        } catch {
+            return false
+        }
+    }
+
+    /**
+     * Copies one already-accounted intrinsic byte range into a fixed buffer.
+     * The explicit range prevents a growable backing store from widening the
+     * copy between its limit check and snapshot.
+     * @param {ArrayBufferLike} buffer Source buffer.
+     * @param {number} byteOffset Captured byte offset.
+     * @param {number} byteLength Captured byte length.
+     * @returns {ArrayBuffer} Fixed owned snapshot.
+     */
+    static copyBuffer(buffer, byteOffset, byteLength) {
+        try {
+            const source = new UINT8_ARRAY_CONSTRUCTOR(
+                buffer,
+                byteOffset,
+                byteLength
+            )
+            const copy = new UINT8_ARRAY_CONSTRUCTOR(byteLength)
+            UINT8_ARRAY_SET.call(copy, source)
+            return TYPED_ARRAY_BUFFER_GETTER.call(copy)
+        } catch {
+            throw new TypeError(
+                'Worker request binary data changed while it was copied.'
+            )
+        }
+    }
+}
+
+Object.freeze(WorkerBinaryData.prototype)
+Object.freeze(WorkerBinaryData)