@tokentop/ttop 0.2.2

package/src/plugins/registry.ts

@@ -0,0 +1,251 @@
+import type {
+  AnyPlugin,
+  PluginType,
+  PluginByType,
+  ProviderPlugin,
+  AgentPlugin,
+  ThemePlugin,
+  NotificationPlugin,
+} from './types/index.ts';
+import { loadLocalPlugin, loadNpmPlugin, discoverLocalPlugins, resolvePluginPath } from './loader.ts';
+import { installAllNpmPlugins, resolveNpmPluginPath } from './npm-installer.ts';
+import type { PluginsConfig } from '@/config/schema.ts';
+
+export type PluginSource = 'builtin' | 'local' | 'npm';
+
+type PluginStore = {
+  provider: Map<string, ProviderPlugin>;
+  agent: Map<string, AgentPlugin>;
+  theme: Map<string, ThemePlugin>;
+  notification: Map<string, NotificationPlugin>;
+};
+
+class PluginRegistryImpl {
+  private plugins: PluginStore = {
+    provider: new Map(),
+    agent: new Map(),
+    theme: new Map(),
+    notification: new Map(),
+  };
+
+  private sources = new Map<string, PluginSource>();
+  private initialized = false;
+
+  private sourceKey(type: string, id: string): string {
+    return `${type}-${id}`;
+  }
+
+  register(plugin: AnyPlugin, source: PluginSource = 'builtin'): void {
+    const key = this.sourceKey(plugin.type, plugin.id);
+    const existingSource = this.sources.get(key);
+
+    if (existingSource === 'builtin' && source !== 'builtin') {
+      return;
+    }
+
+    this.sources.set(key, source);
+    switch (plugin.type) {
+      case 'provider':
+        if (this.plugins.provider.has(plugin.id)) {
+          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
+        }
+        this.plugins.provider.set(plugin.id, plugin);
+        break;
+      case 'agent':
+        if (this.plugins.agent.has(plugin.id)) {
+          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
+        }
+        this.plugins.agent.set(plugin.id, plugin);
+        break;
+      case 'theme':
+        if (this.plugins.theme.has(plugin.id)) {
+          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
+        }
+        this.plugins.theme.set(plugin.id, plugin);
+        break;
+      case 'notification':
+        if (this.plugins.notification.has(plugin.id)) {
+          console.warn(`Plugin "${plugin.id}" already registered, overwriting`);
+        }
+        this.plugins.notification.set(plugin.id, plugin);
+        break;
+    }
+  }
+
+  unregister(type: PluginType, id: string): boolean {
+    return this.plugins[type].delete(id);
+  }
+
+  get<T extends PluginType>(type: T, id: string): PluginByType[T] | undefined {
+    return this.plugins[type].get(id) as PluginByType[T] | undefined;
+  }
+
+  getAll<T extends PluginType>(type: T): PluginByType[T][] {
+    return [...this.plugins[type].values()] as PluginByType[T][];
+  }
+
+  getAllPlugins(): AnyPlugin[] {
+    return [
+      ...this.plugins.provider.values(),
+      ...this.plugins.agent.values(),
+      ...this.plugins.theme.values(),
+      ...this.plugins.notification.values(),
+    ];
+  }
+
+  has(type: PluginType, id: string): boolean {
+    return this.plugins[type].has(id);
+  }
+
+  count(type?: PluginType): number {
+    if (type) {
+      return this.plugins[type].size;
+    }
+    return (
+      this.plugins.provider.size +
+      this.plugins.agent.size +
+      this.plugins.theme.size +
+      this.plugins.notification.size
+    );
+  }
+
+  getSource(type: PluginType, id: string): PluginSource | undefined {
+    return this.sources.get(this.sourceKey(type, id));
+  }
+
+  async loadBuiltinPlugins(): Promise<void> {
+    const [providers, agents, themes, notifications] = await Promise.all([
+      import('./providers/index.ts'),
+      import('./agents/index.ts'),
+      import('./themes/index.ts'),
+      import('./notifications/index.ts'),
+    ]);
+
+    for (const plugin of Object.values(providers)) {
+      if (isProviderPlugin(plugin)) this.register(plugin, 'builtin');
+    }
+
+    for (const plugin of Object.values(agents)) {
+      if (isAgentPlugin(plugin)) this.register(plugin, 'builtin');
+    }
+
+    for (const plugin of Object.values(themes)) {
+      if (isThemePlugin(plugin)) this.register(plugin, 'builtin');
+    }
+
+    for (const plugin of Object.values(notifications)) {
+      if (isNotificationPlugin(plugin)) this.register(plugin, 'builtin');
+    }
+  }
+
+  async loadLocalPlugins(extraPaths: string[] = []): Promise<void> {
+    const discoveredPaths = await discoverLocalPlugins();
+    const resolvedExtraPaths = extraPaths.map(p => resolvePluginPath(p));
+    const allPaths = [...discoveredPaths, ...resolvedExtraPaths];
+
+    for (const pluginPath of allPaths) {
+      const result = await loadLocalPlugin(pluginPath);
+      if (result.success && result.plugin) {
+        this.register(result.plugin, 'local');
+        console.info(`Loaded local plugin: ${result.plugin.name} (${result.plugin.id})`);
+      } else {
+        console.warn(`Failed to load plugin from ${pluginPath}: ${result.error}`);
+      }
+    }
+  }
+
+  async loadNpmPlugins(packages: string[]): Promise<void> {
+    const installResults = await installAllNpmPlugins(packages);
+    for (const ir of installResults) {
+      if (ir.error) {
+        console.warn(`Failed to install npm plugin ${ir.name}: ${ir.error}`);
+        continue;
+      }
+      if (ir.installed) {
+        console.info(`Installed npm plugin: ${ir.name}@${ir.version}`);
+      }
+    }
+
+    for (const packageName of packages) {
+      const resolvedPath = resolveNpmPluginPath(packageName);
+      const result = await loadNpmPlugin(packageName, resolvedPath);
+      if (result.success && result.plugin) {
+        this.register(result.plugin, 'npm');
+        console.info(`Loaded npm plugin: ${result.plugin.name} (${packageName})`);
+      } else {
+        console.warn(`Failed to load npm plugin ${packageName}: ${result.error}`);
+      }
+    }
+  }
+
+  disablePlugin(type: PluginType, id: string): boolean {
+    return this.plugins[type].delete(id);
+  }
+
+  async initialize(config?: {
+    plugins?: Partial<PluginsConfig>;
+    cliPlugins?: string[];
+  }): Promise<void> {
+    if (this.initialized) return;
+
+    await this.loadBuiltinPlugins();
+
+    const localPaths = [
+      ...(config?.plugins?.local ?? []),
+      ...(config?.cliPlugins ?? []),
+    ];
+    await this.loadLocalPlugins(localPaths);
+
+    const npmPackages = config?.plugins?.npm ?? [];
+    if (npmPackages.length > 0) {
+      await this.loadNpmPlugins(npmPackages);
+    }
+
+    const disabled = config?.plugins?.disabled ?? [];
+    for (const pluginId of disabled) {
+      for (const type of ['provider', 'agent', 'theme', 'notification'] as PluginType[]) {
+        if (this.has(type, pluginId)) {
+          this.disablePlugin(type, pluginId);
+          console.info(`Disabled plugin: ${pluginId}`);
+        }
+      }
+    }
+
+    this.initialized = true;
+    console.info(
+      `Plugin registry initialized: ${this.count('provider')} providers, ` +
+        `${this.count('agent')} agents, ${this.count('theme')} themes, ` +
+        `${this.count('notification')} notifications`
+    );
+  }
+}
+
+function hasPluginShape(obj: unknown): obj is { id: string; type: string; name: string; version: string } {
+  return (
+    obj !== null &&
+    typeof obj === 'object' &&
+    'id' in obj &&
+    'type' in obj &&
+    'name' in obj &&
+    'version' in obj
+  );
+}
+
+function isProviderPlugin(obj: unknown): obj is ProviderPlugin {
+  return hasPluginShape(obj) && obj.type === 'provider';
+}
+
+function isAgentPlugin(obj: unknown): obj is AgentPlugin {
+  return hasPluginShape(obj) && obj.type === 'agent';
+}
+
+function isThemePlugin(obj: unknown): obj is ThemePlugin {
+  return hasPluginShape(obj) && obj.type === 'theme';
+}
+
+function isNotificationPlugin(obj: unknown): obj is NotificationPlugin {
+  return hasPluginShape(obj) && obj.type === 'notification';
+}
+
+export const pluginRegistry = new PluginRegistryImpl();
+export type PluginRegistry = PluginRegistryImpl;

package/src/plugins/sandbox-guard.test.ts

@@ -0,0 +1,191 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import {
+  deepFreeze,
+  getActivePluginGuard,
+  installGlobalFetchGuard,
+  runInPluginGuard,
+} from './sandbox-guard.ts';
+import { PluginPermissionError } from './types/base.ts';
+
+const originalFetch = globalThis.fetch;
+const fetchCalls: string[] = [];
+
+const mockFetch: typeof fetch = Object.assign(
+  (input: string | URL | Request, _init?: RequestInit): Promise<Response> => {
+    const url = typeof input === 'string'
+      ? input
+      : input instanceof URL
+        ? input.toString()
+        : input.url;
+    fetchCalls.push(url);
+    return Promise.resolve(new Response('ok', { status: 200 }));
+  },
+  { preconnect: originalFetch.preconnect },
+);
+
+describe('deepFreeze', () => {
+  test('freezes a plain object', () => {
+    const obj = { a: 1 };
+    deepFreeze(obj);
+
+    expect(Object.isFrozen(obj)).toBe(true);
+  });
+
+  test('freezes nested objects recursively', () => {
+    const obj = {
+      top: {
+        child: {
+          value: 1,
+        },
+      },
+    };
+
+    deepFreeze(obj);
+
+    expect(Object.isFrozen(obj)).toBe(true);
+    expect(Object.isFrozen(obj.top)).toBe(true);
+    expect(Object.isFrozen(obj.top.child)).toBe(true);
+  });
+
+  test('returns the same reference', () => {
+    const obj = { nested: { value: 1 } };
+    const frozen = deepFreeze(obj);
+
+    expect(frozen).toBe(obj);
+  });
+
+  test('handles null and undefined gracefully', () => {
+    expect(deepFreeze(null)).toBeNull();
+    expect(deepFreeze(undefined)).toBeUndefined();
+  });
+
+  test('handles circular references without infinite loop', () => {
+    const obj: { self?: unknown; nested: { parent?: unknown } } = {
+      nested: {},
+    };
+    obj.self = obj;
+    obj.nested.parent = obj;
+
+    const frozen = deepFreeze(obj);
+
+    expect(frozen).toBe(obj);
+    expect(Object.isFrozen(obj)).toBe(true);
+    expect(Object.isFrozen(obj.nested)).toBe(true);
+  });
+
+  test('handles already-frozen objects', () => {
+    const obj = Object.freeze({ already: true });
+
+    const frozen = deepFreeze(obj);
+
+    expect(frozen).toBe(obj);
+    expect(Object.isFrozen(frozen)).toBe(true);
+  });
+});
+
+describe('runInPluginGuard and getActivePluginGuard', () => {
+  test('returns undefined outside guard', () => {
+    expect(getActivePluginGuard()).toBeUndefined();
+  });
+
+  test('returns plugin context inside guard', () => {
+    const context = runInPluginGuard('plugin-a', {}, () => getActivePluginGuard());
+
+    expect(context).toBeDefined();
+    expect(context?.pluginId).toBe('plugin-a');
+  });
+
+  test('preserves context across async/await', async () => {
+    const context = await runInPluginGuard('plugin-async', {}, async () => {
+      await Promise.resolve();
+      return getActivePluginGuard();
+    });
+
+    expect(context).toBeDefined();
+    expect(context?.pluginId).toBe('plugin-async');
+  });
+
+  test('nested guards use the innermost context', () => {
+    const contexts = runInPluginGuard('outer-plugin', {}, () => {
+      const outerBefore = getActivePluginGuard();
+      const inner = runInPluginGuard('inner-plugin', {}, () => getActivePluginGuard());
+      const outerAfter = getActivePluginGuard();
+
+      return { outerBefore, inner, outerAfter };
+    });
+
+    expect(contexts.outerBefore?.pluginId).toBe('outer-plugin');
+    expect(contexts.inner?.pluginId).toBe('inner-plugin');
+    expect(contexts.outerAfter?.pluginId).toBe('outer-plugin');
+  });
+});
+
+describe('installGlobalFetchGuard', () => {
+  beforeAll(() => {
+    globalThis.fetch = mockFetch;
+    installGlobalFetchGuard();
+  });
+
+  afterAll(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test('outside guard, fetch calls pass through', async () => {
+    fetchCalls.length = 0;
+
+    const response = await fetch('https://outside-guard.example');
+
+    expect(response.status).toBe(200);
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0]).toContain('outside-guard.example');
+  });
+
+  test('inside guard with no network permission throws PluginPermissionError', () => {
+    expect(() => {
+      runInPluginGuard('plugin-no-network', {}, () => {
+        void fetch('https://blocked.example');
+      });
+    }).toThrow(PluginPermissionError);
+  });
+
+  test('inside guard with allowedDomains blocks unlisted domains', () => {
+    expect(() => {
+      runInPluginGuard(
+        'plugin-allowlist',
+        {
+          network: {
+            enabled: true,
+            allowedDomains: ['allowed.example'],
+          },
+        },
+        () => {
+          void fetch('https://not-allowed.example/path');
+        },
+      );
+    }).toThrow(PluginPermissionError);
+  });
+
+  test('inside guard with allowedDomains allows listed domains and subdomains', async () => {
+    fetchCalls.length = 0;
+
+    const response = await runInPluginGuard(
+      'plugin-allowlist',
+      {
+        network: {
+          enabled: true,
+          allowedDomains: ['allowed.example'],
+        },
+      },
+      async () => {
+        const rootResponse = await fetch('https://allowed.example/path');
+        await fetch('https://api.allowed.example/path');
+        return rootResponse;
+      },
+    );
+
+    expect(response.status).toBe(200);
+    expect(fetchCalls).toHaveLength(2);
+    expect(fetchCalls[0]).toContain('allowed.example/path');
+    expect(fetchCalls[1]).toContain('api.allowed.example/path');
+  });
+});

package/src/plugins/sandbox-guard.ts

@@ -0,0 +1,155 @@
+/**
+ * Sandbox guard — runtime enforcement for plugin permission boundaries.
+ *
+ * Uses AsyncLocalStorage to track which plugin is currently executing.
+ * This enables enforcement even when plugins bypass the provided `ctx` and
+ * call global APIs directly (e.g. `globalThis.fetch`).
+ *
+ * Two layers:
+ * 1. **Global fetch guard** — intercepts all `fetch()` calls and enforces
+ *    network domain allowlists when running inside a plugin context.
+ * 2. **Deep-freeze** — prevents plugins from mutating the PluginContext.
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { PluginPermissionError, type PluginPermissions } from './types/base.ts';
+import { createPluginLogger } from './sandbox.ts';
+
+// ---------------------------------------------------------------------------
+// Plugin execution context (AsyncLocalStorage)
+// ---------------------------------------------------------------------------
+
+export interface PluginGuardContext {
+  readonly pluginId: string;
+  readonly permissions: PluginPermissions;
+}
+
+const pluginGuardStorage = new AsyncLocalStorage<PluginGuardContext>();
+
+/**
+ * Get the currently-executing plugin context, if any.
+ * Returns undefined when called outside of a plugin method invocation.
+ */
+export function getActivePluginGuard(): PluginGuardContext | undefined {
+  return pluginGuardStorage.getStore();
+}
+
+/**
+ * Run a function within a plugin's guard context.
+ * All code executed within `fn` (including async continuations) will
+ * have the plugin's permissions available via `getActivePluginGuard()`.
+ */
+export function runInPluginGuard<T>(
+  pluginId: string,
+  permissions: PluginPermissions,
+  fn: () => T,
+): T {
+  return pluginGuardStorage.run({ pluginId, permissions }, fn);
+}
+
+// ---------------------------------------------------------------------------
+// Global fetch guard
+// ---------------------------------------------------------------------------
+
+let fetchGuardInstalled = false;
+
+/**
+ * Install a global fetch interceptor that enforces plugin network permissions.
+ *
+ * When code runs inside `runInPluginGuard()`, all `fetch()` calls are checked
+ * against the plugin's `permissions.network.allowedDomains`. Calls outside of
+ * a plugin context pass through unmodified.
+ *
+ * This is idempotent — calling it multiple times is safe.
+ */
+export function installGlobalFetchGuard(): void {
+  if (fetchGuardInstalled) return;
+
+  const originalFetch = globalThis.fetch;
+
+  const guardedFetch: typeof fetch = Object.assign(
+    function guardedFetch(
+      input: string | URL | Request,
+      init?: RequestInit,
+    ): Promise<Response> {
+      const guard = pluginGuardStorage.getStore();
+
+      if (!guard) {
+        return originalFetch(input, init);
+      }
+
+      const { pluginId, permissions } = guard;
+
+      if (!permissions.network?.enabled) {
+        const log = createPluginLogger(pluginId);
+        log.error('Network access blocked — plugin has not declared network permissions');
+        throw new PluginPermissionError(
+          pluginId,
+          'network',
+          'Network access not permitted',
+        );
+      }
+
+      const allowedDomains = permissions.network.allowedDomains;
+      if (allowedDomains && allowedDomains.length > 0) {
+        const url = typeof input === 'string'
+          ? new URL(input)
+          : input instanceof URL
+            ? input
+            : new URL(input.url);
+
+        const isAllowed = allowedDomains.some(
+          (domain) =>
+            url.hostname === domain || url.hostname.endsWith(`.${domain}`),
+        );
+
+        if (!isAllowed) {
+          const log = createPluginLogger(pluginId);
+          log.error(`Network blocked: domain "${url.hostname}" not in allowlist [${allowedDomains.join(', ')}]`);
+          throw new PluginPermissionError(
+            pluginId,
+            'network',
+            `Domain "${url.hostname}" not in allowlist: ${allowedDomains.join(', ')}`,
+          );
+        }
+      }
+
+      return originalFetch(input, init);
+    },
+    { preconnect: originalFetch.preconnect },
+  );
+
+  globalThis.fetch = guardedFetch;
+  fetchGuardInstalled = true;
+}
+
+// ---------------------------------------------------------------------------
+// Deep freeze
+// ---------------------------------------------------------------------------
+
+const frozenObjects = new WeakSet<object>();
+
+/**
+ * Recursively freeze an object and all of its enumerable properties.
+ * Safe against circular references via WeakSet tracking.
+ * Skips functions (they may need internal state) and already-frozen objects.
+ */
+export function deepFreeze<T>(obj: T): T {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== 'object') return obj;
+
+  const o = obj as object;
+
+  if (frozenObjects.has(o) || Object.isFrozen(o)) return obj;
+  frozenObjects.add(o);
+
+  Object.freeze(o);
+
+  for (const value of Object.values(o)) {
+    if (value !== null && typeof value === 'object') {
+      deepFreeze(value);
+    }
+  }
+
+  return obj;
+}