corporateai 0.0.1

package/server/src/services/plugin-runtime-sandbox.ts

@@ -0,0 +1,222 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import vm from "node:vm";
+import type { PaperclipPluginManifestV1 } from "@corporateai/shared";
+import type { PluginCapabilityValidator } from "./plugin-capability-validator.js";
+
+export class PluginSandboxError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PluginSandboxError";
+  }
+}
+
+/**
+ * Sandbox runtime options used when loading a plugin worker module.
+ *
+ * `allowedModuleSpecifiers` controls which bare module specifiers are permitted.
+ * `allowedModules` provides concrete host-provided bindings for those specifiers.
+ */
+export interface PluginSandboxOptions {
+  entrypointPath: string;
+  allowedModuleSpecifiers?: ReadonlySet<string>;
+  allowedModules?: Readonly<Record<string, Record<string, unknown>>>;
+  allowedGlobals?: Record<string, unknown>;
+  timeoutMs?: number;
+}
+
+/**
+ * Operation-level runtime gate for plugin host API calls.
+ * Every host operation must be checked against manifest capabilities before execution.
+ */
+export interface CapabilityScopedInvoker {
+  invoke<T>(operation: string, fn: () => Promise<T> | T): Promise<T>;
+}
+
+interface LoadedModule {
+  namespace: Record<string, unknown>;
+}
+
+const DEFAULT_TIMEOUT_MS = 2_000;
+const MODULE_PATH_SUFFIXES = ["", ".js", ".mjs", ".cjs", "/index.js", "/index.mjs", "/index.cjs"];
+const DEFAULT_GLOBALS: Record<string, unknown> = {
+  console,
+  setTimeout,
+  clearTimeout,
+  setInterval,
+  clearInterval,
+  URL,
+  URLSearchParams,
+  TextEncoder,
+  TextDecoder,
+  AbortController,
+  AbortSignal,
+};
+
+export function createCapabilityScopedInvoker(
+  manifest: PaperclipPluginManifestV1,
+  validator: PluginCapabilityValidator,
+): CapabilityScopedInvoker {
+  return {
+    async invoke<T>(operation: string, fn: () => Promise<T> | T): Promise<T> {
+      validator.assertOperation(manifest, operation);
+      return await fn();
+    },
+  };
+}
+
+/**
+ * Load a CommonJS plugin module in a VM context with explicit module import allow-listing.
+ *
+ * Security properties:
+ * - no implicit access to host globals like `process`
+ * - no unrestricted built-in module imports
+ * - relative imports are resolved only inside the plugin root directory
+ */
+export async function loadPluginModuleInSandbox(
+  options: PluginSandboxOptions,
+): Promise<LoadedModule> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const allowedSpecifiers = options.allowedModuleSpecifiers ?? new Set<string>();
+  const entrypointPath = path.resolve(options.entrypointPath);
+  const pluginRoot = path.dirname(entrypointPath);
+
+  const context = vm.createContext({
+    ...DEFAULT_GLOBALS,
+    ...options.allowedGlobals,
+  });
+
+  const moduleCache = new Map<string, Record<string, unknown>>();
+  const allowedModules = options.allowedModules ?? {};
+
+  const realPluginRoot = realpathSync(pluginRoot);
+
+  const loadModuleSync = (modulePath: string): Record<string, unknown> => {
+    const resolvedPath = resolveModulePathSync(path.resolve(modulePath));
+    const realPath = realpathSync(resolvedPath);
+
+    if (!isWithinRoot(realPath, realPluginRoot)) {
+      throw new PluginSandboxError(
+        `Import '${modulePath}' escapes plugin root and is not allowed`,
+      );
+    }
+
+    const cached = moduleCache.get(realPath);
+    if (cached) return cached;
+
+    const code = readModuleSourceSync(realPath);
+
+    if (looksLikeEsm(code)) {
+      throw new PluginSandboxError(
+        "Sandbox loader only supports CommonJS modules. Build plugin worker entrypoints as CJS for sandboxed loading.",
+      );
+    }
+
+    const module = { exports: {} as Record<string, unknown> };
+    // Cache the module before execution to preserve CommonJS cycle semantics.
+    moduleCache.set(realPath, module.exports);
+
+    const requireInSandbox = (specifier: string): Record<string, unknown> => {
+      if (!specifier.startsWith(".") && !specifier.startsWith("/")) {
+        if (!allowedSpecifiers.has(specifier)) {
+          throw new PluginSandboxError(
+            `Import denied for module '${specifier}'. Add an explicit sandbox allow-list entry.`,
+          );
+        }
+
+        const binding = allowedModules[specifier];
+        if (!binding) {
+          throw new PluginSandboxError(
+            `Bare module '${specifier}' is allow-listed but no host binding is registered.`,
+          );
+        }
+
+        return binding;
+      }
+
+      const candidatePath = path.resolve(path.dirname(realPath), specifier);
+      return loadModuleSync(candidatePath);
+    };
+
+    // Inject the CJS module arguments into the context so the script can call
+    // the wrapper immediately. This is critical: the timeout in runInContext
+    // only applies during script evaluation. By including the self-invocation
+    // `(fn)(exports, module, ...)` in the script text, the timeout also covers
+    // the actual module body execution — preventing infinite loops from hanging.
+    const sandboxArgs = {
+      __paperclip_exports: module.exports,
+      __paperclip_module: module,
+      __paperclip_require: requireInSandbox,
+      __paperclip_filename: realPath,
+      __paperclip_dirname: path.dirname(realPath),
+    };
+    // Temporarily inject args into the context, run, then remove to avoid pollution.
+    Object.assign(context, sandboxArgs);
+    const wrapped = `(function (exports, module, require, __filename, __dirname) {\n${code}\n})(__paperclip_exports, __paperclip_module, __paperclip_require, __paperclip_filename, __paperclip_dirname)`;
+    const script = new vm.Script(wrapped, { filename: realPath });
+    try {
+      script.runInContext(context, { timeout: timeoutMs });
+    } finally {
+      for (const key of Object.keys(sandboxArgs)) {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete (context as Record<string, unknown>)[key];
+      }
+    }
+
+    const normalizedExports = normalizeModuleExports(module.exports);
+    moduleCache.set(realPath, normalizedExports);
+    return normalizedExports;
+  };
+
+  const entryExports = loadModuleSync(entrypointPath);
+
+  return {
+    namespace: { ...entryExports },
+  };
+}
+
+function resolveModulePathSync(candidatePath: string): string {
+  for (const suffix of MODULE_PATH_SUFFIXES) {
+    const fullPath = `${candidatePath}${suffix}`;
+    if (existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+
+  throw new PluginSandboxError(`Unable to resolve module import at path '${candidatePath}'`);
+}
+
+/**
+ * True when `targetPath` is inside `rootPath` (or equals rootPath), false otherwise.
+ * Uses `path.relative` so sibling-prefix paths (e.g. `/root-a` vs `/root`) cannot bypass checks.
+ */
+function isWithinRoot(targetPath: string, rootPath: string): boolean {
+  const relative = path.relative(rootPath, targetPath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function readModuleSourceSync(modulePath: string): string {
+  try {
+    return readFileSync(modulePath, "utf8");
+  } catch (error) {
+    throw new PluginSandboxError(
+      `Failed to read sandbox module '${modulePath}': ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+function normalizeModuleExports(exportsValue: unknown): Record<string, unknown> {
+  if (typeof exportsValue === "object" && exportsValue !== null) {
+    return exportsValue as Record<string, unknown>;
+  }
+
+  return { default: exportsValue };
+}
+
+/**
+ * Lightweight guard to reject ESM syntax in the VM CommonJS loader.
+ */
+function looksLikeEsm(code: string): boolean {
+  return /(^|\n)\s*import\s+/m.test(code) || /(^|\n)\s*export\s+/m.test(code);
+}
+

package/server/src/services/plugin-secrets-handler.ts

@@ -0,0 +1,355 @@
+/**
+ * Plugin secrets host-side handler — resolves secret references through the
+ * Paperclip secret provider system.
+ *
+ * When a plugin worker calls `ctx.secrets.resolve(secretRef)`, the JSON-RPC
+ * request arrives at the host with `{ secretRef }`. This module provides the
+ * concrete `HostServices.secrets` adapter that:
+ *
+ * 1. Parses the `secretRef` string to identify the secret.
+ * 2. Looks up the secret record and its latest version in the database.
+ * 3. Delegates to the configured `SecretProviderModule` to decrypt /
+ *    resolve the raw value.
+ * 4. Returns the resolved plaintext value to the worker.
+ *
+ * ## Secret Reference Format
+ *
+ * A `secretRef` is a **secret UUID** — the primary key (`id`) of a row in
+ * the `company_secrets` table. Operators place these UUIDs into plugin
+ * config values; plugin workers resolve them at execution time via
+ * `ctx.secrets.resolve(secretId)`.
+ *
+ * ## Security Invariants
+ *
+ * - Resolved values are **never** logged, persisted, or included in error
+ *   messages (per PLUGIN_SPEC.md §22).
+ * - The handler is capability-gated: only plugins with `secrets.read-ref`
+ *   declared in their manifest may call it (enforced by `host-client-factory`).
+ * - The host handler itself does not cache resolved values. Each call goes
+ *   through the secret provider to honour rotation.
+ *
+ * @see PLUGIN_SPEC.md §22 — Secrets
+ * @see host-client-factory.ts — capability gating
+ * @see services/secrets.ts — secretService used by agent env bindings
+ */
+
+import { eq, and, desc } from "drizzle-orm";
+import type { Db } from "@corporateai/db";
+import { companySecrets, companySecretVersions, pluginConfig } from "@corporateai/db";
+import type { SecretProvider } from "@corporateai/shared";
+import { getSecretProvider } from "../secrets/provider-registry.js";
+import { pluginRegistryService } from "./plugin-registry.js";
+
+// ---------------------------------------------------------------------------
+// Error helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a sanitised error that never leaks secret material.
+ * Only the ref identifier is included; never the resolved value.
+ */
+function secretNotFound(secretRef: string): Error {
+  const err = new Error(`Secret not found: ${secretRef}`);
+  err.name = "SecretNotFoundError";
+  return err;
+}
+
+function secretVersionNotFound(secretRef: string): Error {
+  const err = new Error(`No version found for secret: ${secretRef}`);
+  err.name = "SecretVersionNotFoundError";
+  return err;
+}
+
+function invalidSecretRef(secretRef: string): Error {
+  const err = new Error(`Invalid secret reference: ${secretRef}`);
+  err.name = "InvalidSecretRefError";
+  return err;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/** UUID v4 regex for validating secretRef format. */
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Check whether a secretRef looks like a valid UUID.
+ */
+function isUuid(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+/**
+ * Collect the property paths (dot-separated keys) whose schema node declares
+ * `format: "secret-ref"`. Only top-level and nested `properties` are walked —
+ * this mirrors the flat/nested object shapes that `JsonSchemaForm` renders.
+ */
+function collectSecretRefPaths(
+  schema: Record<string, unknown> | null | undefined,
+): Set<string> {
+  const paths = new Set<string>();
+  if (!schema || typeof schema !== "object") return paths;
+
+  function walk(node: Record<string, unknown>, prefix: string): void {
+    const props = node.properties as Record<string, Record<string, unknown>> | undefined;
+    if (!props || typeof props !== "object") return;
+    for (const [key, propSchema] of Object.entries(props)) {
+      if (!propSchema || typeof propSchema !== "object") continue;
+      const path = prefix ? `${prefix}.${key}` : key;
+      if (propSchema.format === "secret-ref") {
+        paths.add(path);
+      }
+      // Recurse into nested object schemas
+      if (propSchema.type === "object") {
+        walk(propSchema, path);
+      }
+    }
+  }
+
+  walk(schema, "");
+  return paths;
+}
+
+/**
+ * Extract secret reference UUIDs from a plugin's configJson, scoped to only
+ * the fields annotated with `format: "secret-ref"` in the schema.
+ *
+ * When no schema is provided, falls back to collecting all UUID-shaped strings
+ * (backwards-compatible for plugins without a declared instanceConfigSchema).
+ */
+export function extractSecretRefsFromConfig(
+  configJson: unknown,
+  schema?: Record<string, unknown> | null,
+): Set<string> {
+  const refs = new Set<string>();
+  if (configJson == null || typeof configJson !== "object") return refs;
+
+  const secretPaths = collectSecretRefPaths(schema);
+
+  // If schema declares secret-ref paths, extract only those values.
+  if (secretPaths.size > 0) {
+    for (const dotPath of secretPaths) {
+      const keys = dotPath.split(".");
+      let current: unknown = configJson;
+      for (const k of keys) {
+        if (current == null || typeof current !== "object") { current = undefined; break; }
+        current = (current as Record<string, unknown>)[k];
+      }
+      if (typeof current === "string" && isUuid(current)) {
+        refs.add(current);
+      }
+    }
+    return refs;
+  }
+
+  // Fallback: no schema or no secret-ref annotations — collect all UUIDs.
+  // This preserves backwards compatibility for plugins that omit
+  // instanceConfigSchema.
+  function walkAll(value: unknown): void {
+    if (typeof value === "string") {
+      if (isUuid(value)) refs.add(value);
+    } else if (Array.isArray(value)) {
+      for (const item of value) walkAll(item);
+    } else if (value !== null && typeof value === "object") {
+      for (const v of Object.values(value as Record<string, unknown>)) walkAll(v);
+    }
+  }
+
+  walkAll(configJson);
+  return refs;
+}
+
+// ---------------------------------------------------------------------------
+// Handler factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Input shape for the `secrets.resolve` handler.
+ *
+ * Matches `WorkerToHostMethods["secrets.resolve"][0]` from `protocol.ts`.
+ */
+export interface PluginSecretsResolveParams {
+  /** The secret reference string (a secret UUID). */
+  secretRef: string;
+}
+
+/**
+ * Options for creating the plugin secrets handler.
+ */
+export interface PluginSecretsHandlerOptions {
+  /** Database connection. */
+  db: Db;
+  /**
+   * The plugin ID using this handler.
+   * Used for logging context only; never included in error payloads
+   * that reach the plugin worker.
+   */
+  pluginId: string;
+}
+
+/**
+ * The `HostServices.secrets` adapter for the plugin host-client factory.
+ */
+export interface PluginSecretsService {
+  /**
+   * Resolve a secret reference to its current plaintext value.
+   *
+   * @param params - Contains the `secretRef` (UUID of the secret)
+   * @returns The resolved secret value
+   * @throws {Error} If the secret is not found, has no versions, or
+   *   the provider fails to resolve
+   */
+  resolve(params: PluginSecretsResolveParams): Promise<string>;
+}
+
+/**
+ * Create a `HostServices.secrets` adapter for a specific plugin.
+ *
+ * The returned service looks up secrets by UUID, fetches the latest version
+ * material, and delegates to the appropriate `SecretProviderModule` for
+ * decryption.
+ *
+ * @example
+ * ```ts
+ * const secretsHandler = createPluginSecretsHandler({ db, pluginId });
+ * const handlers = createHostClientHandlers({
+ *   pluginId,
+ *   capabilities: manifest.capabilities,
+ *   services: {
+ *     secrets: secretsHandler,
+ *     // ...
+ *   },
+ * });
+ * ```
+ *
+ * @param options - Database connection and plugin identity
+ * @returns A `PluginSecretsService` suitable for `HostServices.secrets`
+ */
+/** Simple sliding-window rate limiter for secret resolution attempts. */
+function createRateLimiter(maxAttempts: number, windowMs: number) {
+  const attempts = new Map<string, number[]>();
+
+  return {
+    check(key: string): boolean {
+      const now = Date.now();
+      const windowStart = now - windowMs;
+      const existing = (attempts.get(key) ?? []).filter((ts) => ts > windowStart);
+      if (existing.length >= maxAttempts) return false;
+      existing.push(now);
+      attempts.set(key, existing);
+      return true;
+    },
+  };
+}
+
+export function createPluginSecretsHandler(
+  options: PluginSecretsHandlerOptions,
+): PluginSecretsService {
+  const { db, pluginId } = options;
+  const registry = pluginRegistryService(db);
+
+  // Rate limit: max 30 resolution attempts per plugin per minute
+  const rateLimiter = createRateLimiter(30, 60_000);
+
+  let cachedAllowedRefs: Set<string> | null = null;
+  let cachedAllowedRefsExpiry = 0;
+  const CONFIG_CACHE_TTL_MS = 30_000; // 30 seconds, matches event bus TTL
+
+  return {
+    async resolve(params: PluginSecretsResolveParams): Promise<string> {
+      const { secretRef } = params;
+
+      // ---------------------------------------------------------------
+      // 0. Rate limiting — prevent brute-force UUID enumeration
+      // ---------------------------------------------------------------
+      if (!rateLimiter.check(pluginId)) {
+        const err = new Error("Rate limit exceeded for secret resolution");
+        err.name = "RateLimitExceededError";
+        throw err;
+      }
+
+      // ---------------------------------------------------------------
+      // 1. Validate the ref format
+      // ---------------------------------------------------------------
+      if (!secretRef || typeof secretRef !== "string" || secretRef.trim().length === 0) {
+        throw invalidSecretRef(secretRef ?? "<empty>");
+      }
+
+      const trimmedRef = secretRef.trim();
+
+      if (!isUuid(trimmedRef)) {
+        throw invalidSecretRef(trimmedRef);
+      }
+
+      // ---------------------------------------------------------------
+      // 1b. Scope check — only allow secrets referenced in this plugin's config
+      // ---------------------------------------------------------------
+      const now = Date.now();
+      if (!cachedAllowedRefs || now > cachedAllowedRefsExpiry) {
+        const [configRow, plugin] = await Promise.all([
+          db
+            .select()
+            .from(pluginConfig)
+            .where(eq(pluginConfig.pluginId, pluginId))
+            .then((rows) => rows[0] ?? null),
+          registry.getById(pluginId),
+        ]);
+
+        const schema = (plugin?.manifestJson as unknown as Record<string, unknown> | null)
+          ?.instanceConfigSchema as Record<string, unknown> | undefined;
+        cachedAllowedRefs = extractSecretRefsFromConfig(configRow?.configJson, schema);
+        cachedAllowedRefsExpiry = now + CONFIG_CACHE_TTL_MS;
+      }
+
+      if (!cachedAllowedRefs.has(trimmedRef)) {
+        // Return "not found" to avoid leaking whether the secret exists
+        throw secretNotFound(trimmedRef);
+      }
+
+      // ---------------------------------------------------------------
+      // 2. Look up the secret record by UUID
+      // ---------------------------------------------------------------
+      const secret = await db
+        .select()
+        .from(companySecrets)
+        .where(eq(companySecrets.id, trimmedRef))
+        .then((rows) => rows[0] ?? null);
+
+      if (!secret) {
+        throw secretNotFound(trimmedRef);
+      }
+
+      // ---------------------------------------------------------------
+      // 3. Fetch the latest version's material
+      // ---------------------------------------------------------------
+      const versionRow = await db
+        .select()
+        .from(companySecretVersions)
+        .where(
+          and(
+            eq(companySecretVersions.secretId, secret.id),
+            eq(companySecretVersions.version, secret.latestVersion),
+          ),
+        )
+        .then((rows) => rows[0] ?? null);
+
+      if (!versionRow) {
+        throw secretVersionNotFound(trimmedRef);
+      }
+
+      // ---------------------------------------------------------------
+      // 4. Resolve through the appropriate secret provider
+      // ---------------------------------------------------------------
+      const provider = getSecretProvider(secret.provider as SecretProvider);
+      const resolved = await provider.resolveVersion({
+        material: versionRow.material as Record<string, unknown>,
+        externalRef: secret.externalRef,
+      });
+
+      return resolved;
+    },
+  };
+}
+