Add plugin security boundaries.

PR Details:
- Restricts unsafe plugin behavior
- Improves system safety

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,7 +2,7 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement plugin resource limits:
-- Enforce CPU/memory caps
-- Maintain stability
+Implement plugin security boundaries:
+- Restrict unsafe operations
+- Enforce access rules
 - Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,5 @@
-Add plugin resource limits.
+Add plugin security boundaries.
 
 PR Details:
-- Prevents resource abuse
+- Restricts unsafe plugin behavior
+- Improves system safety

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Limits enforced
-[ ] System stable
-[ ] No degradation
+[ ] Restrictions enforced
+[ ] No unsafe access
+[ ] Normal plugins unaffected
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -820,7 +820,7 @@
 ### Track G — Extensibility Readiness
 - [x] validate plugin/extension patterns
 - [x] validate adding new systems is clean
-- [.] validate external integration points
+- [x] validate external integration points
 - [x] ensure future phases can build cleanly
 
 ### Track H — Final Stability Gate

docs/pr/BUILD_PR.md

@@ -1,21 +1,21 @@
-# BUILD_PR_LEVEL_20_7_OVERLAY_PLUGIN_RESOURCE_LIMITS
+# BUILD_PR_LEVEL_20_8_OVERLAY_PLUGIN_SECURITY_BOUNDARIES
 
 ## Purpose
-Enforce resource limits on overlay plugins.
+Establish security boundaries for overlay plugins.
 
 ## Roadmap Improvement
-Prevents plugins from degrading system performance.
+Enhances system safety by restricting plugin capabilities.
 
 ## Scope
-- Define CPU/memory limits
-- Enforce limits
-- Validate behavior under limits
+- Define allowed plugin operations
+- Restrict unsafe access
+- Validate secure execution
 
 ## Test Steps
-1. Run heavy plugin
-2. Verify limits enforced
-3. Confirm system stability
+1. Attempt restricted operations
+2. Verify enforcement
+3. Confirm normal plugin behavior unaffected
 
 ## Expected
-- Limits enforced
-- No system degradation
+- Security rules enforced
+- No unsafe access

samples/phase-19/shared/overlay/createPhase19OverlayPluginRegistry.js

@@ -19,6 +19,18 @@ const DEFAULT_RESOURCE_LIMITS = Object.freeze({
   maxHeapUsedBytes: 512 * 1024 * 1024,
   maxHeapDeltaBytes: 8 * 1024 * 1024,
 });
+const UNSAFE_CONTEXT_KEYS = Object.freeze([
+  'process',
+  'global',
+  'globalThis',
+  'window',
+  'document',
+  'Function',
+  'eval',
+  'require',
+  'module',
+]);
+const RESERVED_PROTOTYPE_KEYS = Object.freeze(['__proto__', 'prototype', 'constructor']);
 
 function normalizePluginId(pluginId) {
   return String(pluginId || '').trim();
@@ -32,6 +44,75 @@ function normalizeLimit(value, fallback) {
   return numeric;
 }
 
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function sanitizePluginContextValue(value, depth = 0) {
+  if (depth > 6) {
+    return null;
+  }
+  if (value === null) {
+    return null;
+  }
+  const valueType = typeof value;
+  if (valueType === 'string' || valueType === 'number' || valueType === 'boolean') {
+    return value;
+  }
+  if (valueType === 'bigint') {
+    return Number(value);
+  }
+  if (valueType === 'undefined' || valueType === 'function' || valueType === 'symbol') {
+    return undefined;
+  }
+
+  if (Array.isArray(value)) {
+    const result = [];
+    for (let i = 0; i < value.length; i += 1) {
+      const sanitized = sanitizePluginContextValue(value[i], depth + 1);
+      if (typeof sanitized === 'undefined') {
+        continue;
+      }
+      result.push(sanitized);
+    }
+    return result;
+  }
+
+  if (!isPlainObject(value)) {
+    return undefined;
+  }
+
+  const output = {};
+  const keys = Object.keys(value);
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = String(keys[i] || '').trim();
+    if (!key) {
+      continue;
+    }
+    if (UNSAFE_CONTEXT_KEYS.includes(key) || RESERVED_PROTOTYPE_KEYS.includes(key)) {
+      continue;
+    }
+    const sanitized = sanitizePluginContextValue(value[key], depth + 1);
+    if (typeof sanitized === 'undefined') {
+      continue;
+    }
+    output[key] = sanitized;
+  }
+  return output;
+}
+
+function sanitizePluginContext(context = {}) {
+  const sanitized = sanitizePluginContextValue(context, 0);
+  if (!sanitized || typeof sanitized !== 'object') {
+    return {};
+  }
+  return sanitized;
+}
+
 function normalizeResourceLimits(resourceLimits = {}) {
   return Object.freeze({
     maxHookDurationMs: normalizeLimit(resourceLimits?.maxHookDurationMs, DEFAULT_RESOURCE_LIMITS.maxHookDurationMs),
@@ -251,17 +332,70 @@ export default function createPhase19OverlayPluginRegistry({
     return pluginRecordMap.get(normalizedPluginId) ?? null;
   }
 
-  function getReadonlyRegistryView() {
-    return createReadonlyFacade(api, [
-      'getPlugin',
-      'getPluginState',
-      'getPluginExtensionId',
-      'getPluginMetrics',
-      'listPluginMetrics',
-      'getPluginDiagnostics',
-      'listPluginDiagnostics',
-      'listPlugins',
-    ]);
+  function getReadonlyRegistryView(pluginId = '') {
+    const normalizedPluginId = normalizePluginId(pluginId);
+    return Object.freeze({
+      getPlugin(requestedPluginId = normalizedPluginId) {
+        const requestedId = normalizePluginId(requestedPluginId);
+        if (!requestedId || requestedId !== normalizedPluginId) {
+          return null;
+        }
+        return api.getPlugin(requestedId);
+      },
+      getPluginState(requestedPluginId = normalizedPluginId) {
+        const requestedId = normalizePluginId(requestedPluginId);
+        if (!requestedId || requestedId !== normalizedPluginId) {
+          return '';
+        }
+        return api.getPluginState(requestedId);
+      },
+      getPluginExtensionId(requestedPluginId = normalizedPluginId) {
+        const requestedId = normalizePluginId(requestedPluginId);
+        if (!requestedId || requestedId !== normalizedPluginId) {
+          return '';
+        }
+        return api.getPluginExtensionId(requestedId);
+      },
+      getPluginMetrics(requestedPluginId = normalizedPluginId) {
+        const requestedId = normalizePluginId(requestedPluginId);
+        if (!requestedId || requestedId !== normalizedPluginId) {
+          return null;
+        }
+        return api.getPluginMetrics(requestedId);
+      },
+      getPluginDiagnostics(requestedPluginId = normalizedPluginId) {
+        const requestedId = normalizePluginId(requestedPluginId);
+        if (!requestedId || requestedId !== normalizedPluginId) {
+          return null;
+        }
+        return api.getPluginDiagnostics(requestedId);
+      },
+      listPlugins() {
+        const plugin = api.getPlugin(normalizedPluginId);
+        if (!plugin) {
+          return Object.freeze([]);
+        }
+        return Object.freeze([{
+          id: normalizedPluginId,
+          state: api.getPluginState(normalizedPluginId),
+          extensionId: api.getPluginExtensionId(normalizedPluginId),
+        }]);
+      },
+      listPluginMetrics() {
+        const metrics = api.getPluginMetrics(normalizedPluginId);
+        if (!metrics) {
+          return Object.freeze([]);
+        }
+        return Object.freeze([{ pluginId: normalizedPluginId, metrics }]);
+      },
+      listPluginDiagnostics() {
+        const diagnostics = api.getPluginDiagnostics(normalizedPluginId);
+        if (!diagnostics) {
+          return Object.freeze([]);
+        }
+        return Object.freeze([diagnostics]);
+      },
+    });
   }
 
   function getReadonlyFrameworkView() {
@@ -454,13 +588,19 @@ export default function createPhase19OverlayPluginRegistry({
     try {
       const previousHookPluginId = activeHookPluginId;
       activeHookPluginId = record.plugin.id;
+      const safeContext = sanitizePluginContext(context);
       const lifecycleContext = deepFreezeValue({
-        ...context,
+        ...safeContext,
         phase,
         pluginId: record.plugin.id,
         extensionId: record.extension.id,
-        registry: getReadonlyRegistryView(),
+        registry: getReadonlyRegistryView(record.plugin.id),
         expansionFramework: getReadonlyFrameworkView(),
+        security: {
+          mode: 'isolated',
+          scopedRegistryAccess: true,
+          unsafeContextKeysRemoved: UNSAFE_CONTEXT_KEYS,
+        },
       });
       try {
         hook(lifecycleContext);
@@ -697,10 +837,15 @@ export default function createPhase19OverlayPluginRegistry({
       normalizedPlugin,
       normalizedPlugin.createOverlayExtension
         ? normalizedPlugin.createOverlayExtension({
+          ...sanitizePluginContext(context),
           pluginId,
-          registry: getReadonlyRegistryView(),
+          registry: getReadonlyRegistryView(pluginId),
           expansionFramework: getReadonlyFrameworkView(),
-          ...context,
+          security: {
+            mode: 'isolated',
+            scopedRegistryAccess: true,
+            unsafeContextKeysRemoved: UNSAFE_CONTEXT_KEYS,
+          },
         })
         : normalizedPlugin.extension
     );

tests/runtime/Phase19OverlayPluginRegistry.test.mjs

@@ -39,8 +39,17 @@ function assertPluginRegistrationAndRuntimeCompatibility() {
     createOverlayExtension(context) {
       accessSurface.registryRegisterPluginType = typeof context?.registry?.registerPlugin;
       accessSurface.registryGetPluginStateType = typeof context?.registry?.getPluginState;
+      accessSurface.registryOtherStateFromCreate = context?.registry?.getPluginState?.('phase19.other');
+      accessSurface.createListPluginsLength = Array.isArray(context?.registry?.listPlugins?.())
+        ? context.registry.listPlugins().length
+        : -1;
       accessSurface.frameworkRegisterExtensionType = typeof context?.expansionFramework?.registerExtension;
       accessSurface.frameworkListExtensionIdsType = typeof context?.expansionFramework?.listExtensionIds;
+      accessSurface.contextSafeToken = context?.safeToken;
+      accessSurface.contextUnsafeProcessType = typeof context?.process;
+      accessSurface.contextUnsafeWindowType = typeof context?.window;
+      accessSurface.contextNestedFnType = typeof context?.nested?.fn;
+      accessSurface.securityModeFromCreate = context?.security?.mode;
       return definePhase19OverlayExtension({
         id: 'phase19.runtime.plugin.overlay',
         overlays: [
@@ -63,12 +72,49 @@ function assertPluginRegistrationAndRuntimeCompatibility() {
         ],
       });
     },
+    init(context) {
+      accessSurface.securityModeFromInit = context?.security?.mode;
+      accessSurface.scopedRegistryAccess = context?.security?.scopedRegistryAccess;
+      accessSurface.registryOtherStateFromInit = context?.registry?.getPluginState?.('phase19.other');
+      accessSurface.initListPlugins = context?.registry?.listPlugins?.();
+      accessSurface.initListPluginMetrics = context?.registry?.listPluginMetrics?.();
+      accessSurface.initUnsafeDocumentType = typeof context?.document;
+    },
+  }, {
+    context: {
+      safeToken: 'ok-token',
+      process: { env: 'unsafe' },
+      window: { location: 'unsafe' },
+      nested: {
+        keep: true,
+        fn() {},
+      },
+      document: {
+        body: {},
+      },
+    },
   });
 
   assert.equal(accessSurface.registryRegisterPluginType, 'undefined', 'Plugin creation context must not expose mutating registry methods.');
   assert.equal(accessSurface.registryGetPluginStateType, 'function', 'Plugin creation context should expose read-only registry introspection.');
+  assert.equal(accessSurface.registryOtherStateFromCreate, '', 'Scoped registry view should block access to other plugin state during creation.');
+  assert.equal(accessSurface.createListPluginsLength, 0, 'Scoped registry view should not expose other plugins during creation context.');
   assert.equal(accessSurface.frameworkRegisterExtensionType, 'undefined', 'Plugin creation context must not expose mutating framework methods.');
   assert.equal(accessSurface.frameworkListExtensionIdsType, 'function', 'Plugin creation context should expose read-only framework introspection.');
+  assert.equal(accessSurface.contextSafeToken, 'ok-token', 'Sanitized context should preserve safe primitive keys.');
+  assert.equal(accessSurface.contextUnsafeProcessType, 'undefined', 'Sanitized context should strip unsafe process key.');
+  assert.equal(accessSurface.contextUnsafeWindowType, 'undefined', 'Sanitized context should strip unsafe window key.');
+  assert.equal(accessSurface.contextNestedFnType, 'undefined', 'Sanitized context should strip nested function values.');
+  assert.equal(accessSurface.securityModeFromCreate, 'isolated', 'Security context should be available during extension creation.');
+  assert.equal(accessSurface.securityModeFromInit, 'isolated', 'Security context should be available during lifecycle hooks.');
+  assert.equal(accessSurface.scopedRegistryAccess, true, 'Security context should mark scoped registry access.');
+  assert.equal(accessSurface.registryOtherStateFromInit, '', 'Scoped registry view should block access to other plugin state during lifecycle hooks.');
+  assert.equal(Array.isArray(accessSurface.initListPlugins), true, 'Scoped registry list should be present during lifecycle hooks.');
+  assert.equal(accessSurface.initListPlugins.length, 1, 'Scoped registry list should include only current plugin entry.');
+  assert.equal(accessSurface.initListPlugins[0]?.id, 'phase19.runtime.plugin', 'Scoped registry list should only include current plugin id.');
+  assert.equal(Array.isArray(accessSurface.initListPluginMetrics), true, 'Scoped registry metrics list should be available.');
+  assert.equal(accessSurface.initListPluginMetrics.length, 1, 'Scoped registry metrics should include only current plugin.');
+  assert.equal(accessSurface.initUnsafeDocumentType, 'undefined', 'Lifecycle context should strip unsafe document key.');
 
   assert.deepEqual(
     result,