feat: enhance security by implementing pinned property handling in proxies and tests

Author: frontegg-david

docs/enclave/core-libraries/enclave-browser/security-architecture.mdx

@@ -136,6 +136,12 @@ Every global object exposed to user code is wrapped in a `Proxy` that blocks acc
 
 The proxy behavior is configurable per security level. At `STRICT` and `SECURE` levels, accessing blocked properties throws an error. At `PERMISSIVE`, it returns `undefined`.
 
+#### Pinned properties
+
+A JavaScript `get` trap must report the exact value of a non-configurable, non-writable own data property, so the proxy can neither wrap nor hide one. Primitives in that position are reported as-is — this covers constants such as `Math.PI` and hardened slots pinned to `undefined`. An **object or function** in that position is refused with a `SecurityError` regardless of `throwOnBlocked`, because returning the reference would put an unwrapped object graph in reach of sandboxed code, and that graph's prototype chain leads to a `Function` constructor.
+
+This matters for host values that pin object-valued internals: a Zod schema pins `_zod` this way, and every class pins `prototype`. Hand sandboxed code plain serialized data rather than live host objects — a structurally cloned or JSON-projected value has no pinned members and reads normally.
+
 Additionally, dangerous static methods on `Object` are neutralized: `defineProperty`, `defineProperties`, `setPrototypeOf`, `getOwnPropertyDescriptor`, and `getOwnPropertyDescriptors`.
 
 ### Layer 7: Safe Runtime Wrappers

libs/core/src/__tests__/enclave.host-reference-leak.spec.ts

@@ -284,13 +284,25 @@ describe('custom-global results must not leak a raw host object via a pinned pro
     }
   }
 
+  // Disposal must happen even when an assertion throws, otherwise a failing test leaves its
+  // worker pool alive and jest hangs on the surviving handles.
+  const created: Enclave[] = [];
+
+  afterEach(() => {
+    while (created.length > 0) {
+      created.pop()?.dispose();
+    }
+  });
+
   function enclaveWithHostGlobals(globals: Record<string, unknown>): Enclave {
-    return new Enclave({
+    const enclave = new Enclave({
       securityLevel: 'STANDARD',
       toolHandler: async () => ({ ok: true }),
       allowFunctionsInGlobals: true,
       globals,
     });
+    created.push(enclave);
+    return enclave;
   }
 
   it('blocks the reported PoC (pinned property → host Function → execSync)', async () => {
@@ -308,8 +320,9 @@ describe('custom-global results must not leak a raw host object via a pinned pro
     `;
     const result = await enclave.run(code);
     assertNoRce(result);
+    // The run must fail at the membrane, not somewhere incidental further down the chain.
     expect(result.success).toBe(false);
-    enclave.dispose();
+    expect(result.error?.message).toMatch(/Access to '_zod' is blocked/);
   });
 
   it('refuses the pinned property itself rather than returning a raw reference', async () => {
@@ -328,7 +341,6 @@ describe('custom-global results must not leak a raw host object via a pinned pro
     const result = await enclave.run(code);
     expect(result.success).toBe(true);
     expect(result.value).toEqual({ denied: expect.stringMatching(/blocked/i) });
-    enclave.dispose();
   });
 
   it('stays strict through nested reads and chained calls', async () => {
@@ -349,7 +361,6 @@ describe('custom-global results must not leak a raw host object via a pinned pro
     const result = await enclave.run(code);
     expect(result.success).toBe(true);
     expect(result.value).toEqual({ denied: expect.stringMatching(/blocked/i) });
-    enclave.dispose();
   });
 
   it('still exposes primitive-valued pinned properties from host globals', async () => {
@@ -370,7 +381,6 @@ describe('custom-global results must not leak a raw host object via a pinned pro
     const result = await enclave.run(code);
     expect(result.success).toBe(true);
     expect(result.value).toBe(3);
-    enclave.dispose();
   });
 
   it('still passes ordinary host-global data through unchanged', async () => {
@@ -386,11 +396,10 @@ describe('custom-global results must not leak a raw host object via a pinned pro
     const result = await enclave.run(code);
     expect(result.success).toBe(true);
     expect(result.value).toEqual({ name: 'users:list', kind: 'object', prop: 'number' });
-    enclave.dispose();
   });
 
   it('leaves realm-owned intrinsics usable (host mode must not touch them)', async () => {
-    const enclave = new Enclave({ securityLevel: 'STANDARD', toolHandler: async () => ({ ok: true }) });
+    const enclave = enclaveWithHostGlobals({});
     const code = `
       async function __ag_main() {
         return {
@@ -403,6 +412,5 @@ describe('custom-global results must not leak a raw host object via a pinned pro
     const result = await enclave.run(code);
     expect(result.success).toBe(true);
     expect(result.value).toEqual({ joined: 'x-x-x', repeated: 'abab', parsed: 1 });
-    enclave.dispose();
   });
 });

libs/core/src/__tests__/secure-proxy.spec.ts

@@ -410,15 +410,15 @@ describe('SecureProxy', () => {
       expect(() => (proxy as any).pinned).toThrow(/blocked/i);
     });
 
-    it('should not leak a frozen class prototype through the blocked-property path', () => {
+    it('should refuse a class prototype, which is pinned by the language', () => {
       class Widget {
         value = 1;
       }
-      Object.freeze(Widget.prototype);
       const proxy = createSecureProxy(Widget) as unknown as Record<string, unknown>;
 
-      // `prototype` on a class is non-configurable and non-writable, so the old invariant
-      // concession returned it raw — from there `.constructor.constructor` is host Function.
+      // `prototype` on a class is already non-configurable and non-writable, so this read is
+      // decided by the invariant branch rather than the blocked-property list. The old
+      // concession returned it raw, and `.constructor.constructor` from there is host Function.
       expect(() => proxy['prototype']).toThrow(/blocked/i);
     });