fix(engine): natively construct DOMException and URIError on boundary crossing

Resolves the D3a deferral by dynamically resolving JS exception constructors
(like globalThis.DOMException) when marshaling native exceptions, allowing
host op errors to surface as true instances to JavaScript.

Author: Thanga-Ganapathy

crates/engine/src/convert.rs

@@ -85,6 +85,38 @@ pub(crate) fn build_exception<'s>(
     err: &dyn IntoException,
 ) -> v8::Local<'s, v8::Value> {
     let class = err.exception_class();
+
+    // Fallback/dynamic constructor lookup for classes V8 doesn't provide natively.
+    let try_construct = |scope: &mut v8::PinScope<'s, '_>, class_name: &str, args: &[v8::Local<'s, v8::Value>]| -> Option<v8::Local<'s, v8::Value>> {
+        let context = scope.get_current_context();
+        let global = context.global(scope);
+        let key = v8::String::new(scope, class_name)?;
+        let constructor = global.get(scope, key.into())?;
+        if constructor.is_function() {
+            let constructor = v8::Local::<v8::Function>::try_from(constructor).ok()?;
+            let exception = constructor.new_instance(scope, args)?;
+            Some(exception.into())
+        } else {
+            None
+        }
+    };
+
+    if let ExceptionClass::DomException(name) = class {
+        if let Some(msg_val) = v8::String::new(scope, &err.exception_message()) {
+            if let Some(name_val) = v8::String::new(scope, name) {
+                if let Some(ex) = try_construct(scope, "DOMException", &[msg_val.into(), name_val.into()]) {
+                    return ex;
+                }
+            }
+        }
+    } else if let ExceptionClass::UriError = class {
+        if let Some(msg_val) = v8::String::new(scope, &err.exception_message()) {
+            if let Some(ex) = try_construct(scope, "URIError", &[msg_val.into()]) {
+                return ex;
+            }
+        }
+    }
+
     let text = match class.dom_exception_name() {
         Some(name) => format!("{name}: {}", err.exception_message()),
         None => err.exception_message(),
@@ -95,8 +127,7 @@ pub(crate) fn build_exception<'s>(
         ExceptionClass::ReferenceError => v8::Exception::reference_error(scope, message),
         ExceptionClass::SyntaxError => v8::Exception::syntax_error(scope, message),
         ExceptionClass::TypeError => v8::Exception::type_error(scope, message),
-        // `Error`, plus `URIError`/`DOMException` (no bare-V8 constructor) and
-        // any future class: default to a plain `Error`.
+        // `Error` and any future class: default to a plain `Error`.
         _ => v8::Exception::error(scope, message),
     }
 }

crates/runtime/conformance/exceptions.js

@@ -0,0 +1,63 @@
+// Engine exception reconciliation tests.
+
+test("engine-thrown DOMException is a true DOMException instance (NotSupportedError)", async () => {
+  let caught = null;
+  try {
+    await crypto.subtle.digest("UNKNOWN", new Uint8Array());
+  } catch (e) {
+    caught = e;
+  }
+  
+  assertEquals(caught !== null, true);
+  assertEquals(caught instanceof DOMException, true);
+  assertEquals(caught.name, "NotSupportedError");
+  assertEquals(caught.message.includes("unsupported digest"), true);
+});
+
+test("engine-thrown DOMException with a different name (DataError)", async () => {
+  let caught = null;
+  try {
+    // Importing invalid key material throws a DataError from the native op
+    await crypto.subtle.importKey("spki", new Uint8Array([1, 2, 3]), { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, true, ["verify"]);
+  } catch (e) {
+    caught = e;
+  }
+  
+  assertEquals(caught !== null, true);
+  assertEquals(caught instanceof DOMException, true);
+  assertEquals(caught.name, "DataError");
+});
+
+test("engine-thrown native TypeError is a true TypeError instance", async () => {
+  let caught = null;
+  try {
+    // Passing a number where a string is expected
+    await crypto.subtle.digest(123, new Uint8Array());
+  } catch (e) {
+    caught = e;
+  }
+  
+  assertEquals(caught !== null, true);
+  assertEquals(caught instanceof TypeError, true);
+  assertEquals(caught.name, "TypeError");
+});
+
+test("engine-thrown DOMException with OperationError name", async () => {
+  let caught = null;
+  try {
+    // AES-GCM decrypt with corrupted ciphertext throws OperationError
+    const key = await crypto.subtle.generateKey({ name: "AES-GCM", length: 128 }, false, ["encrypt", "decrypt"]);
+    const iv = new Uint8Array(12);
+    const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, new Uint8Array([1, 2, 3]));
+    // Corrupt the ciphertext tag
+    const corrupted = new Uint8Array(ct);
+    corrupted[corrupted.length - 1] ^= 1;
+    await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, corrupted);
+  } catch (e) {
+    caught = e;
+  }
+  
+  assertEquals(caught !== null, true);
+  assertEquals(caught instanceof DOMException, true);
+  assertEquals(caught.name, "OperationError");
+});

docs/DECISIONS.md

@@ -58,14 +58,13 @@ Status: **Locked** · **Proposed** · **Open** (needs maintainer sign-off) · **
 > - **Engine trait now extracted** (resolving the Phase 1 "concrete only" note).
 >   `engine::Engine` is object-safe and names no V8 type; `runtime` holds a
 >   `Box<dyn Engine>`. The boundary held — no V8 type appears in `runtime`.
-> - **`DOMException` is partially real (updated Phase 4).** The prelude now
->   defines a real `globalThis.DOMException` class, so prelude APIs (atob/btoa,
->   structuredClone, Abort) throw the correct type with `instanceof Error`. The
->   remaining gap: errors thrown from the **engine** (Rust side, e.g. a capability
->   denial → `NotAllowedError`) still surface as a plain `Error` with a
->   name-prefixed message, because the engine has no handle to the JS class. A
->   later phase reconciles the two paths (engine throws the prelude's
->   `DOMException`).
+> - **`DOMException` is fully real.** The prelude defines a real
+>   `globalThis.DOMException` class, so prelude APIs (atob/btoa,
+>   structuredClone, Abort) throw the correct type with `instanceof Error`.
+>   Errors thrown natively from the **engine** (Rust side, e.g. a capability
+>   denial → `NotAllowedError`) now correctly resolve this class from
+>   `globalThis` during construction, surfacing as true `DOMException` instances
+>   to JS.
 > - **Async readiness is observed only on `tick`.** With no reactor (std-only,
 >   `Waker::noop`), a pending op's future is polled when the embedder ticks, not
 >   when its work actually becomes ready. *Reason:* the driven model (D4); a real

docs/SPEC.md

@@ -140,7 +140,7 @@ Productionizing the standalone runtime *and* stabilizing the embeddable API. ESM
 
 **Deferrals:**
 - **Panic-across-FFI containment** (`catch_unwind` around op/timer/reject callbacks, per D12) — ☑ **implemented in Phase 9**: a host op panic is contained as a JS exception, not an abort (assumes `panic = "unwind"`). (DECISIONS D15.)
-- **`DOMException` engine reconciliation** — the JS class exists (Phase 4 prelude), but errors thrown from the engine still surface as `Error` with a name-prefixed message. (DECISIONS D3a.)
+- **`DOMException` engine reconciliation** — ☑ **implemented**: the engine dynamically resolves `globalThis.DOMException` when marshaling a native `DOMException`, surfacing it as a proper instance of the JS class (resolves DECISIONS D3a).
 - **Byte/BYOB streams** (`ReadableByteStreamController`, BYOB readers) — ☑ **implemented in Phase 9** (copy-based, no ArrayBuffer transfer/detach; DECISIONS D19). Default streams + encoding streams shipped in Phase 5.
 - **Streaming `fetch` request bodies** → a follow-up; Phase 6 buffers the request body and streams the response (DECISIONS D20).
 - **`crypto.subtle` minor gaps.** The algorithm set is complete (digest/HMAC/AES-GCM/CBC/CTR, HKDF/PBKDF2, ECDSA/ECDH, RSA PKCS1-v1_5/PSS/OAEP — DECISIONS D9). Remaining edges: AES-CTR supports only 32/64/128-bit counter widths (others → `NotSupportedError`); RSA-OAEP **labels must be UTF-8** (the `rsa` 0.9 API limitation; non-UTF-8 → `NotSupportedError`); EC keys import/export as raw/spki/pkcs8/jwk and RSA as spki/pkcs8/jwk; `deriveKey` targets AES-* and HMAC keys. All asymmetric signing/keygen randomness routes through the Entropy provider, never ambient `OsRng`. RSA carries an **accepted timing-sidechannel advisory** (RUSTSEC-2023-0071) tracked on the SECURITY.md revisit list.

site/app/docs/security/page.jsx

@@ -43,7 +43,8 @@ export default function SecurityDoc() {
       <p className="mt-3 text-zinc-600">
         Every host operation declares the capability it requires. The check
         lives on the native op, not in JavaScript, so it cannot be bypassed by
-        reaching a different module path.
+        reaching a different module path. A denied capability will instantly
+        throw a standard <code>DOMException</code> with the <code>NotAllowedError</code> name.
       </p>
       <div className="mt-5 overflow-hidden rounded-xl border border-zinc-200">
         <table className="w-full text-left text-sm">