circuitjson-toolkit 1.2.1 → 1.4.0

package/src/core/context/CircuitJsonValidationProof.mjs

@@ -53,21 +53,66 @@ export class CircuitJsonValidationProof {
     /**
      * Validates, freezes, and proves one canonical document envelope.
      * @param {Record<string, any>} document Canonical document envelope.
+     * @param {{ standardBuiltins?: boolean }} [options] Proven metadata provenance.
      * @returns {Record<string, any>} The same read-only document envelope.
      */
-    static validateAndAttach(document) {
+    static validateAndAttach(document, options = {}) {
+        const model = CircuitJsonValidationProof.#validateModel(document)
+        return CircuitJsonValidationProof.#attachAndSeal(
+            document,
+            model,
+            options
+        )
+    }
+
+    /**
+     * Validates a clone-owned model, yields to the host, and then seals its
+     * extension envelope without weakening the matching runtime proof.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {{ standardBuiltins?: boolean, yield?: () => Promise<void> | void }} [options] Proven metadata provenance and host scheduler.
+     * @returns {Promise<Record<string, any>>} The same read-only document envelope.
+     */
+    static async validateAndAttachAsync(document, options = {}) {
+        const model = CircuitJsonValidationProof.#validateModel(document)
+        await CircuitJsonValidationProof.#yieldToHost(options?.yield)
+        return CircuitJsonValidationProof.#attachAndSealAsync(document, model, {
+            ...options,
+            yield: () => CircuitJsonValidationProof.#yieldToHost(options?.yield)
+        })
+    }
+
+    /**
+     * Validates and freezes one exact model before any cooperative yield.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @returns {object[]} Stable validated model.
+     */
+    static #validateModel(document) {
         const model = CircuitJsonValidationProof.#requireModelData(document)
+        if (CircuitJsonValidationProof.#matches(document, model)) return model
+        const errors = CircuitJsonValidationAuthority.validateAndFreeze(model)
+        if (errors.length) throw new TypeError(errors[0])
+        if (CircuitJsonValidationProof.#requireModelData(document) !== model) {
+            throw new TypeError(
+                'CircuitJSON document model changed during validation.'
+            )
+        }
+        return model
+    }
+
+    /**
+     * Attaches the private proof and seals the matching document envelope.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {object[]} model Stable validated model.
+     * @param {{ standardBuiltins?: boolean }} options Proven metadata provenance.
+     * @returns {Record<string, any>} Read-only document envelope.
+     */
+    static #attachAndSeal(document, model, options) {
+        if (CircuitJsonValidationProof.#requireModelData(document) !== model) {
+            throw new TypeError(
+                'CircuitJSON document model changed before sealing.'
+            )
+        }
         if (!CircuitJsonValidationProof.#matches(document, model)) {
-            const errors =
-                CircuitJsonValidationAuthority.validateAndFreeze(model)
-            if (errors.length) throw new TypeError(errors[0])
-            if (
-                CircuitJsonValidationProof.#requireModelData(document) !== model
-            ) {
-                throw new TypeError(
-                    'CircuitJSON document model changed during validation.'
-                )
-            }
             Object.defineProperty(document, VALIDATION_PROOF, {
                 configurable: false,
                 enumerable: false,
@@ -80,7 +125,8 @@ export class CircuitJsonValidationProof {
         }
         const readonlyDocument = CircuitJsonReadOnlyDocument.freezeValidated(
             document,
-            model
+            model,
+            options
         )
         if (
             CircuitJsonValidationProof.#requireModelData(readonlyDocument) !==
@@ -94,6 +140,74 @@ export class CircuitJsonValidationProof {
         return readonlyDocument
     }
 
+    /**
+     * Attaches the proof and cooperatively seals a matching clone-owned
+     * document envelope.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @param {object[]} model Stable validated model.
+     * @param {{ standardBuiltins?: boolean, yield: () => Promise<void> }} options Proven provenance and normalized scheduler.
+     * @returns {Promise<Record<string, any>>} Read-only document envelope.
+     */
+    static async #attachAndSealAsync(document, model, options) {
+        if (CircuitJsonValidationProof.#requireModelData(document) !== model) {
+            throw new TypeError(
+                'CircuitJSON document model changed before sealing.'
+            )
+        }
+        if (!CircuitJsonValidationProof.#matches(document, model)) {
+            Object.defineProperty(document, VALIDATION_PROOF, {
+                configurable: false,
+                enumerable: false,
+                value: new CircuitJsonValidationToken(
+                    model,
+                    VALIDATION_TOKEN_SECRET
+                ),
+                writable: false
+            })
+        }
+        const readonlyDocument =
+            await CircuitJsonReadOnlyDocument.freezeValidatedAsync(
+                document,
+                model,
+                options
+            )
+        if (
+            CircuitJsonValidationProof.#requireModelData(readonlyDocument) !==
+                model ||
+            !CircuitJsonValidationProof.#matches(readonlyDocument, model)
+        ) {
+            throw new TypeError(
+                'CircuitJSON document model changed while sealing its validation proof.'
+            )
+        }
+        return readonlyDocument
+    }
+
+    /**
+     * Yields through an injected scheduler, the browser scheduler API, or a
+     * zero-delay host task in that order.
+     * @param {(() => Promise<void> | void) | undefined} yieldControl Optional host scheduler.
+     * @returns {Promise<void>}
+     */
+    static async #yieldToHost(yieldControl) {
+        if (yieldControl !== undefined) {
+            if (typeof yieldControl !== 'function') {
+                throw new TypeError(
+                    'Structured-clone yield control must be a function.'
+                )
+            }
+            await yieldControl()
+            return
+        }
+        const scheduler = globalThis.scheduler
+        const schedulerYield = scheduler?.yield
+        if (typeof schedulerYield === 'function') {
+            await Reflect.apply(schedulerYield, scheduler, [])
+            return
+        }
+        await new Promise((resolve) => globalThis.setTimeout(resolve, 0))
+    }
+
     /**
      * Returns true when an envelope proof matches its current model reference.
      * @param {unknown} document Document candidate.

package/src/core/context/ProtectedExtensionBinaryBoundary.mjs

@@ -1,18 +1,233 @@
 import { BinaryDataSnapshot } from './BinaryDataSnapshot.mjs'
 
 const PROTECTED_BINARY_GETTERS = new WeakSet()
+const CAPTURED_BINARY_PROPERTIES = new WeakSet()
+const PENDING_BINARY_CAPTURES = new WeakMap()
+const BINARY_COPY_CHUNK_BYTES = 64 * 1024
 
 /**
  * Protects byte-backed values embedded in canonical extension containers.
  */
 export class ProtectedExtensionBinaryBoundary {
+    /**
+     * Protects the exact binary properties collected by a proven clone
+     * adoption traversal without rescanning every ordinary container.
+     * @param {{ owner: object, key: PropertyKey }[]} properties Binary properties.
+     * @returns {void}
+     */
+    static protectProperties(properties) {
+        if (!Array.isArray(properties)) {
+            throw new TypeError(
+                'Canonical extension binary properties must be an array.'
+            )
+        }
+        for (const property of properties) {
+            const owner = property?.owner
+            const key = property?.key
+            let descriptor
+            try {
+                descriptor = Object.getOwnPropertyDescriptor(owner, key)
+            } catch {
+                throw new TypeError(
+                    'Canonical extension data could not be inspected safely.'
+                )
+            }
+            if (ProtectedExtensionBinaryBoundary.isProtected(descriptor)) {
+                continue
+            }
+            const captured = ProtectedExtensionBinaryBoundary.captureProperty(
+                owner,
+                key,
+                descriptor
+            )
+            ProtectedExtensionBinaryBoundary.protectCapturedProperty(captured)
+        }
+    }
+
+    /**
+     * Captures one binary property without changing its owner.
+     * @param {object} owner Binary property owner.
+     * @param {PropertyKey} key Binary property key.
+     * @param {PropertyDescriptor | undefined} [knownDescriptor] Previously validated descriptor.
+     * @returns {object} Opaque captured binary property.
+     */
+    static captureProperty(owner, key, knownDescriptor = undefined) {
+        const capture = ProtectedExtensionBinaryBoundary.beginPropertyCapture(
+            owner,
+            key,
+            knownDescriptor
+        )
+        while (
+            !ProtectedExtensionBinaryBoundary.copyPropertyCaptureChunk(
+                capture,
+                Number.MAX_SAFE_INTEGER
+            )
+        ) {
+            // The synchronous API deliberately owns the full payload atomically.
+        }
+        return ProtectedExtensionBinaryBoundary.finishPropertyCapture(capture)
+    }
+
+    /**
+     * Starts one branded binary property capture without copying its payload.
+     * @param {object} owner Binary property owner.
+     * @param {PropertyKey} key Binary property key.
+     * @param {PropertyDescriptor | undefined} [knownDescriptor] Previously validated descriptor.
+     * @returns {object} Opaque pending capture token.
+     * @internal
+     */
+    static beginPropertyCapture(owner, key, knownDescriptor = undefined) {
+        let descriptor = knownDescriptor
+        if (descriptor === undefined) {
+            try {
+                descriptor = Object.getOwnPropertyDescriptor(owner, key)
+            } catch {
+                throw new TypeError(
+                    'Canonical extension data could not be inspected safely.'
+                )
+            }
+        }
+        if (!descriptor || !Object.hasOwn(descriptor, 'value')) {
+            throw new TypeError(
+                'Canonical extension data may contain only data properties.'
+            )
+        }
+        const binary = BinaryDataSnapshot.describeStandard(descriptor.value)
+        if (!binary) {
+            throw new TypeError(
+                'Canonical extension binary property changed during adoption.'
+            )
+        }
+        const capture = Object.freeze({})
+        PENDING_BINARY_CAPTURES.set(capture, {
+            bytes: new Uint8Array(binary.byteLength),
+            descriptor: Object.freeze({ ...descriptor }),
+            key,
+            offset: 0,
+            owner,
+            source: descriptor.value,
+            sourceRange: Object.freeze({ ...binary })
+        })
+        return capture
+    }
+
+    /**
+     * Copies the next bounded portion of one branded binary capture.
+     * @param {object} capture Opaque pending capture token.
+     * @param {number} [maxBytes] Maximum bytes copied in this call.
+     * @returns {boolean} Whether the entire payload has been copied.
+     * @internal
+     */
+    static copyPropertyCaptureChunk(
+        capture,
+        maxBytes = BINARY_COPY_CHUNK_BYTES
+    ) {
+        const state = PENDING_BINARY_CAPTURES.get(capture)
+        if (!state || !Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+            throw new TypeError(
+                'Canonical extension binary capture is not pending.'
+            )
+        }
+        const remaining = state.sourceRange.byteLength - state.offset
+        const count = Math.min(remaining, maxBytes)
+        BinaryDataSnapshot.copyBytesInto(
+            state.sourceRange,
+            state.bytes,
+            state.offset,
+            count
+        )
+        state.offset += count
+        return state.offset === state.sourceRange.byteLength
+    }
+
+    /**
+     * Finalizes one completely copied binary property into a trusted record.
+     * @param {object} capture Opaque pending capture token.
+     * @returns {object} Opaque captured binary property.
+     * @internal
+     */
+    static finishPropertyCapture(capture) {
+        const state = PENDING_BINARY_CAPTURES.get(capture)
+        if (!state || state.offset !== state.sourceRange.byteLength) {
+            throw new TypeError(
+                'Canonical extension binary capture is incomplete.'
+            )
+        }
+        PENDING_BINARY_CAPTURES.delete(capture)
+        const ownedBinary = BinaryDataSnapshot.cloneFromBytes(
+            state.source,
+            state.sourceRange,
+            state.bytes
+        )
+        const ownedRange = BinaryDataSnapshot.describeStandard(ownedBinary)
+        if (!ownedRange) {
+            throw new TypeError(
+                'Canonical extension binary could not be isolated.'
+            )
+        }
+        const captured = Object.freeze({
+            descriptor: state.descriptor,
+            key: state.key,
+            ownedBinary,
+            ownedRange: Object.freeze({ ...ownedRange }),
+            owner: state.owner
+        })
+        CAPTURED_BINARY_PROPERTIES.add(captured)
+        return captured
+    }
+
+    /**
+     * Installs one previously captured binary as a defensive-copy getter after
+     * proving its property descriptor still matches the transferred source.
+     * @param {object} captured Opaque captured binary property.
+     * @returns {void}
+     */
+    static protectCapturedProperty(captured) {
+        if (!CAPTURED_BINARY_PROPERTIES.has(captured)) {
+            throw new TypeError(
+                'Canonical extension binary capture is not trusted.'
+            )
+        }
+        CAPTURED_BINARY_PROPERTIES.delete(captured)
+        let descriptor
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(
+                captured.owner,
+                captured.key
+            )
+        } catch {
+            throw new TypeError(
+                'Canonical extension data could not be inspected safely.'
+            )
+        }
+        if (
+            !ProtectedExtensionBinaryBoundary.#sameDataDescriptor(
+                descriptor,
+                captured.descriptor
+            )
+        ) {
+            throw new TypeError(
+                'Canonical extension binary property changed during adoption.'
+            )
+        }
+        /** @returns {ArrayBuffer | Uint8Array | DataView} A defensive binary copy. */
+        const readBinary = () =>
+            BinaryDataSnapshot.clone(captured.ownedBinary, captured.ownedRange)
+        PROTECTED_BINARY_GETTERS.add(readBinary)
+        Object.defineProperty(captured.owner, captured.key, {
+            configurable: false,
+            enumerable: descriptor.enumerable,
+            get: readBinary
+        })
+    }
+
     /**
      * Replaces owned binary data properties with defensive-copy getters.
      * @param {unknown} root Owned extension graph.
      * @returns {void}
      */
     static protect(root) {
-        if (BinaryDataSnapshot.describe(root)) {
+        if (BinaryDataSnapshot.describeStandard(root)) {
             throw new TypeError(
                 'Canonical extension root must be a plain data container.'
             )
@@ -51,7 +266,7 @@ export class ProtectedExtensionBinaryBoundary {
                     stack.push(child)
                     continue
                 }
-                const binary = BinaryDataSnapshot.describe(child)
+                const binary = BinaryDataSnapshot.describeStandard(child)
                 if (!binary) continue
                 const ownedBinary = child
                 /** @returns {ArrayBuffer | Uint8Array | DataView} A defensive binary copy. */
@@ -98,6 +313,24 @@ export class ProtectedExtensionBinaryBoundary {
         )
     }
 
+    /**
+     * Compares exact ordinary data descriptor semantics without coercion.
+     * @param {PropertyDescriptor | undefined} current Current descriptor.
+     * @param {PropertyDescriptor} expected Previously captured descriptor.
+     * @returns {boolean} Whether both descriptors still match.
+     */
+    static #sameDataDescriptor(current, expected) {
+        return Boolean(
+            current &&
+            Object.hasOwn(current, 'value') &&
+            Object.hasOwn(expected, 'value') &&
+            Object.is(current.value, expected.value) &&
+            current.configurable === expected.configurable &&
+            current.enumerable === expected.enumerable &&
+            current.writable === expected.writable
+        )
+    }
+
     /**
      * Returns true for plain extension containers.
      * @param {unknown} value Candidate value.