Merge pull request #1 from alkimake/adoption/plugin-secret-ref-scope

feat(plugin): scope secret-ref config by company

packages/db/src/migrations/0094_plugin_config_company_scope.sql

@@ -0,0 +1,11 @@
+ALTER TABLE "plugin_config" ADD COLUMN IF NOT EXISTS "company_id" uuid;--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'plugin_config_company_id_companies_id_fk') THEN
+		ALTER TABLE "plugin_config" ADD CONSTRAINT "plugin_config_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;--> statement-breakpoint
+DROP INDEX IF EXISTS "plugin_config_plugin_id_idx";--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "plugin_config_plugin_id_idx" ON "plugin_config" USING btree ("plugin_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "plugin_config_company_id_idx" ON "plugin_config" USING btree ("company_id");--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "plugin_config_legacy_plugin_id_uq" ON "plugin_config" USING btree ("plugin_id") WHERE "plugin_config"."company_id" is null;--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "plugin_config_company_plugin_uq" ON "plugin_config" USING btree ("plugin_id","company_id") WHERE "plugin_config"."company_id" is not null;

packages/db/src/migrations/meta/_journal.json

@@ -659,6 +659,13 @@
       "when": 1780040470886,
       "tag": "0093_giant_green_goblin",
       "breakpoints": true
+    },
+    {
+      "idx": 94,
+      "version": "7",
+      "when": 1780444800000,
+      "tag": "0094_plugin_config_company_scope",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/plugin_config.ts

@@ -1,10 +1,13 @@
-import { pgTable, uuid, text, timestamp, jsonb, uniqueIndex } from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+import { pgTable, uuid, text, timestamp, jsonb, uniqueIndex, index } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
 import { plugins } from "./plugins.js";
 
 /**
- * `plugin_config` table — stores operator-provided instance configuration
+ * `plugin_config` table — stores operator-provided plugin configuration.
- * for each plugin (one row per plugin, enforced by a unique index on
+ *
- * `plugin_id`).
+ * New configuration is company-scoped. Legacy rows may still have a null
+ * `company_id` so existing installs keep working until re-saved.
  *
  * The `config_json` column holds the values that the operator enters in the
  * plugin settings UI. These values are validated at runtime against the
@@ -19,12 +22,21 @@ export const pluginConfig = pgTable(
     pluginId: uuid("plugin_id")
       .notNull()
       .references(() => plugins.id, { onDelete: "cascade" }),
+    companyId: uuid("company_id")
+      .references(() => companies.id, { onDelete: "cascade" }),
     configJson: jsonb("config_json").$type<Record<string, unknown>>().notNull().default({}),
     lastError: text("last_error"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
   },
   (table) => ({
-    pluginIdIdx: uniqueIndex("plugin_config_plugin_id_idx").on(table.pluginId),
+    pluginIdIdx: index("plugin_config_plugin_id_idx").on(table.pluginId),
+    companyIdIdx: index("plugin_config_company_id_idx").on(table.companyId),
+    legacyPluginIdUq: uniqueIndex("plugin_config_legacy_plugin_id_uq")
+      .on(table.pluginId)
+      .where(sql`${table.companyId} is null`),
+    companyPluginUq: uniqueIndex("plugin_config_company_plugin_uq")
+      .on(table.pluginId, table.companyId)
+      .where(sql`${table.companyId} is not null`),
   }),
 );

packages/plugins/sdk/src/host-client-factory.ts

@@ -100,7 +100,7 @@ export class InvocationScopeDeniedError extends Error {
 export interface HostServices {
   /** Provides `config.get`. */
   config: {
-    get(): Promise<Record<string, unknown>>;
+    get(params: WorkerToHostMethods["config.get"][0]): Promise<Record<string, unknown>>;
   };
 
   /** Provides trusted company-scoped local folder helpers. */
@@ -627,8 +627,8 @@ export function createHostClientHandlers(
 
   return {
     // Config
-    "config.get": gated("config.get", async () => {
+    "config.get": gated("config.get", async (params) => {
-      return services.config.get();
+      return services.config.get(params);
     }),
 
     "localFolders.declarations": gated("localFolders.declarations", async (params) => {

packages/plugins/sdk/src/protocol.ts

@@ -672,7 +672,7 @@ export const HOST_TO_WORKER_OPTIONAL_METHODS: readonly HostToWorkerMethodName[]
  */
 export interface WorkerToHostMethods {
   // Config
-  "config.get": [params: Record<string, never>, result: Record<string, unknown>];
+  "config.get": [params: { companyId?: string | null }, result: Record<string, unknown>];
 
   // Trusted local folders
   "localFolders.declarations": [
@@ -809,7 +809,7 @@ export interface WorkerToHostMethods {
 
   // Secrets
   "secrets.resolve": [
-    params: { secretRef: string },
+    params: { secretRef: string; companyId?: string | null },
     result: string,
   ];
 

packages/plugins/sdk/src/types.ts

@@ -425,7 +425,7 @@ export interface PluginConfigClient {
    * Values are validated against the plugin's `instanceConfigSchema` by the
    * host before being passed to the worker.
    */
-  get(): Promise<Record<string, unknown>>;
+  get(params?: { companyId?: string | null }): Promise<Record<string, unknown>>;
 }
 
 export interface PluginLocalFolderProblem {
@@ -656,7 +656,7 @@ export interface PluginSecretsClient {
    * @param secretRef - The secret reference string from plugin config
    * @returns The resolved secret value
    */
-  resolve(secretRef: string): Promise<string>;
+  resolve(secretRef: string, companyId?: string | null): Promise<string>;
 }
 
 /**

packages/plugins/sdk/src/worker-rpc-host.ts

@@ -164,6 +164,10 @@ export interface WorkerRpcHost {
   stop(): void;
 }
 
+interface RuntimeCompanyContext {
+  companyId?: string | null;
+}
+
 // ---------------------------------------------------------------------------
 // Internal: event registration
 // ---------------------------------------------------------------------------
@@ -285,6 +289,7 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
   let currentConfig: Record<string, unknown> = {};
   let databaseNamespace: string | null = null;
   const invocationContextStorage = new AsyncLocalStorage<PluginInvocationContext>();
+  const runtimeCompanyContext = new AsyncLocalStorage<RuntimeCompanyContext>();
 
   // Plugin handler registrations (populated during setup())
   const eventHandlers: EventRegistration[] = [];
@@ -413,8 +418,12 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
       },
 
       config: {
-        async get() {
+        async get(params) {
-          return callHost("config.get", {} as Record<string, never>);
+          if (params && "companyId" in params) {
+            return callHost("config.get", { companyId: params.companyId ?? null });
+          }
+          const companyId = runtimeCompanyContext.getStore()?.companyId ?? null;
+          return callHost("config.get", companyId ? { companyId } : {});
         },
       },
 
@@ -564,8 +573,11 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
       },
 
       secrets: {
-        async resolve(secretRef: string): Promise<string> {
+        async resolve(secretRef: string, companyId?: string | null): Promise<string> {
-          return callHost("secrets.resolve", { secretRef });
+          const scopedCompanyId = arguments.length >= 2
+            ? companyId ?? null
+            : runtimeCompanyContext.getStore()?.companyId ?? null;
+          return callHost("secrets.resolve", { secretRef, companyId: scopedCompanyId });
         },
       },
 
@@ -1467,7 +1479,10 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
       if (registration.filter && !allowsEvent(registration.filter, event)) continue;
 
       try {
-        await registration.fn(event);
+        await runtimeCompanyContext.run(
+          { companyId: event.companyId },
+          () => registration.fn(event),
+        );
       } catch (err) {
         // Log error but continue processing other handlers so one failing
         // handler doesn't prevent the rest from running.
@@ -1507,7 +1522,10 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
         { code: PLUGIN_RPC_ERROR_CODES.METHOD_NOT_IMPLEMENTED },
       );
     }
-    return plugin.definition.onApiRequest(params);
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId },
+      () => plugin.definition.onApiRequest!(params),
+    );
   }
 
   async function handleGetData(params: GetDataParams): Promise<unknown> {
@@ -1515,11 +1533,14 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
     if (!handler) {
       throw new Error(`No data handler registered for key "${params.key}"`);
     }
-    return handler({
+    const handlerParams =
-      ...params.params,
+      params.renderEnvironment === undefined
-      ...(params.companyId === undefined ? {} : { companyId: params.companyId }),
+        ? params.params
-      ...(params.renderEnvironment === undefined ? {} : { renderEnvironment: params.renderEnvironment }),
+        : { ...params.params, renderEnvironment: params.renderEnvironment };
-    });
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId ?? null },
+      () => handler(handlerParams),
+    );
   }
 
   function stringOrNull(value: unknown): string | null {
@@ -1552,13 +1573,14 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
     if (!handler) {
       throw new Error(`No action handler registered for key "${params.key}"`);
     }
-    return handler(
+    const handlerParams =
-      {
+      params.renderEnvironment === undefined
-        ...params.params,
+        ? params.params
-        ...(params.companyId === undefined ? {} : { companyId: params.companyId }),
+        : { ...params.params, renderEnvironment: params.renderEnvironment };
-        ...(params.renderEnvironment === undefined ? {} : { renderEnvironment: params.renderEnvironment }),
+    const actionContext = actionContextFromParams(params);
-      },
+    return runtimeCompanyContext.run(
-      actionContextFromParams(params),
+      { companyId: params.companyId ?? actionContext.companyId },
+      () => handler(handlerParams ?? {}, actionContext),
     );
   }
 
@@ -1567,7 +1589,10 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
     if (!entry) {
       throw new Error(`No tool handler registered for "${params.toolName}"`);
     }
-    return entry.fn(params.parameters, params.runContext);
+    return runtimeCompanyContext.run(
+      { companyId: params.runContext.companyId },
+      () => entry.fn(params.parameters, params.runContext),
+    );
   }
 
   function methodNotImplemented(method: string): Error & { code: number } {
@@ -1590,49 +1615,70 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
     if (!plugin.definition.onEnvironmentProbe) {
       throw methodNotImplemented("environmentProbe");
     }
-    return plugin.definition.onEnvironmentProbe(params);
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId },
+      () => plugin.definition.onEnvironmentProbe!(params),
+    );
   }
 
   async function handleEnvironmentAcquireLease(params: PluginEnvironmentAcquireLeaseParams) {
     if (!plugin.definition.onEnvironmentAcquireLease) {
       throw methodNotImplemented("environmentAcquireLease");
     }
-    return plugin.definition.onEnvironmentAcquireLease(params);
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId },
+      () => plugin.definition.onEnvironmentAcquireLease!(params),
+    );
   }
 
   async function handleEnvironmentResumeLease(params: PluginEnvironmentResumeLeaseParams) {
     if (!plugin.definition.onEnvironmentResumeLease) {
       throw methodNotImplemented("environmentResumeLease");
     }
-    return plugin.definition.onEnvironmentResumeLease(params);
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId },
+      () => plugin.definition.onEnvironmentResumeLease!(params),
+    );
   }
 
   async function handleEnvironmentReleaseLease(params: PluginEnvironmentReleaseLeaseParams) {
     if (!plugin.definition.onEnvironmentReleaseLease) {
       throw methodNotImplemented("environmentReleaseLease");
     }
-    return plugin.definition.onEnvironmentReleaseLease(params);
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId },
+      () => plugin.definition.onEnvironmentReleaseLease!(params),
+    );
   }
 
   async function handleEnvironmentDestroyLease(params: PluginEnvironmentDestroyLeaseParams) {
     if (!plugin.definition.onEnvironmentDestroyLease) {
       throw methodNotImplemented("environmentDestroyLease");
     }
-    return plugin.definition.onEnvironmentDestroyLease(params);
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId },
+      () => plugin.definition.onEnvironmentDestroyLease!(params),
+    );
   }
 
   async function handleEnvironmentRealizeWorkspace(params: PluginEnvironmentRealizeWorkspaceParams) {
     if (!plugin.definition.onEnvironmentRealizeWorkspace) {
       throw methodNotImplemented("environmentRealizeWorkspace");
     }
-    return plugin.definition.onEnvironmentRealizeWorkspace(params);
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId },
+      () => plugin.definition.onEnvironmentRealizeWorkspace!(params),
+    );
   }
 
   async function handleEnvironmentExecute(params: PluginEnvironmentExecuteParams) {
     if (!plugin.definition.onEnvironmentExecute) {
       throw methodNotImplemented("environmentExecute");
     }
-    return plugin.definition.onEnvironmentExecute(params);
+    return runtimeCompanyContext.run(
+      { companyId: params.companyId },
+      () => plugin.definition.onEnvironmentExecute!(params),
+    );
   }
 
   // -----------------------------------------------------------------------

packages/plugins/sdk/tests/worker-rpc-host.test.ts

@@ -296,3 +296,222 @@ describe("worker invocation scope propagation", () => {
     }
   });
 });
+
+describe("startWorkerRpcHost runtime company context", () => {
+  function collectJsonLines(stream: PassThrough) {
+    const queue: unknown[] = [];
+    const waiters: Array<(value: unknown) => void> = [];
+    let buffer = "";
+
+    stream.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      let newlineIndex = buffer.indexOf("\n");
+      while (newlineIndex !== -1) {
+        const line = buffer.slice(0, newlineIndex).trim();
+        buffer = buffer.slice(newlineIndex + 1);
+        if (line) {
+          const message = JSON.parse(line);
+          const waiter = waiters.shift();
+          if (waiter) waiter(message);
+          else queue.push(message);
+        }
+        newlineIndex = buffer.indexOf("\n");
+      }
+    });
+
+    return async function nextMessage(): Promise<any> {
+      const queued = queue.shift();
+      if (queued) return queued;
+      return new Promise((resolve) => waiters.push(resolve));
+    };
+  }
+
+  function writeMessage(stream: PassThrough, message: unknown): void {
+    stream.write(`${JSON.stringify(message)}\n`);
+  }
+
+  it("passes executeTool company context into config and secret host calls", async () => {
+    const stdin = new PassThrough();
+    const stdout = new PassThrough();
+    const nextMessage = collectJsonLines(stdout);
+
+    const plugin = definePlugin({
+      async setup(ctx) {
+        ctx.tools.register(
+          "check-context",
+          {
+            displayName: "Check Context",
+            description: "Checks runtime context propagation",
+            parametersSchema: { type: "object", properties: {} },
+          },
+          async () => {
+            const config = await ctx.config.get();
+            const token = await ctx.secrets.resolve("77777777-7777-4777-8777-777777777777");
+            return { content: `${config.mode}:${token}` };
+          },
+        );
+      },
+    });
+
+    const host = startWorkerRpcHost({ plugin, stdin, stdout });
+
+    try {
+      writeMessage(stdin, {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          manifest: { id: "test-plugin", name: "test-plugin", version: "1.0.0" },
+          config: {},
+          instanceInfo: { instanceId: "inst-1", hostVersion: "0.0.0-test" },
+          apiVersion: 1,
+        },
+      });
+      await expect(nextMessage()).resolves.toMatchObject({ id: 1, result: { ok: true } });
+
+      writeMessage(stdin, {
+        jsonrpc: "2.0",
+        id: 2,
+        method: "executeTool",
+        params: {
+          toolName: "check-context",
+          parameters: {},
+          runContext: {
+            agentId: "agent-1",
+            runId: "run-1",
+            companyId: "company-1",
+            projectId: "project-1",
+          },
+        },
+      });
+
+      const configRequest = await nextMessage();
+      expect(configRequest).toMatchObject({
+        method: "config.get",
+        params: { companyId: "company-1" },
+      });
+      writeMessage(stdin, {
+        jsonrpc: "2.0",
+        id: configRequest.id,
+        result: { mode: "company-config" },
+      });
+
+      const secretRequest = await nextMessage();
+      expect(secretRequest).toMatchObject({
+        method: "secrets.resolve",
+        params: {
+          secretRef: "77777777-7777-4777-8777-777777777777",
+          companyId: "company-1",
+        },
+      });
+      writeMessage(stdin, {
+        jsonrpc: "2.0",
+        id: secretRequest.id,
+        result: "company-secret",
+      });
+
+      await expect(nextMessage()).resolves.toMatchObject({
+        id: 2,
+        result: { content: "company-config:company-secret" },
+      });
+    } finally {
+      host.stop();
+      stdin.destroy();
+      stdout.destroy();
+    }
+  });
+
+  it("preserves explicit null company context in config and secret host calls", async () => {
+    const stdin = new PassThrough();
+    const stdout = new PassThrough();
+    const nextMessage = collectJsonLines(stdout);
+
+    const plugin = definePlugin({
+      async setup(ctx) {
+        ctx.tools.register(
+          "check-explicit-null",
+          {
+            displayName: "Check Explicit Null",
+            description: "Checks explicit null runtime context propagation",
+            parametersSchema: { type: "object", properties: {} },
+          },
+          async () => {
+            const config = await ctx.config.get({ companyId: null });
+            const token = await ctx.secrets.resolve(
+              "77777777-7777-4777-8777-777777777777",
+              null,
+            );
+            return { content: `${config.mode}:${token}` };
+          },
+        );
+      },
+    });
+
+    const host = startWorkerRpcHost({ plugin, stdin, stdout });
+
+    try {
+      writeMessage(stdin, {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          manifest: { id: "test-plugin", name: "test-plugin", version: "1.0.0" },
+          config: {},
+          instanceInfo: { instanceId: "inst-1", hostVersion: "0.0.0-test" },
+          apiVersion: 1,
+        },
+      });
+      await expect(nextMessage()).resolves.toMatchObject({ id: 1, result: { ok: true } });
+
+      writeMessage(stdin, {
+        jsonrpc: "2.0",
+        id: 2,
+        method: "executeTool",
+        params: {
+          toolName: "check-explicit-null",
+          parameters: {},
+          runContext: {
+            agentId: "agent-1",
+            runId: "run-1",
+            companyId: "company-1",
+            projectId: "project-1",
+          },
+        },
+      });
+
+      const configRequest = await nextMessage();
+      expect(configRequest).toMatchObject({
+        method: "config.get",
+        params: { companyId: null },
+      });
+      writeMessage(stdin, {
+        jsonrpc: "2.0",
+        id: configRequest.id,
+        result: { mode: "global-config" },
+      });
+
+      const secretRequest = await nextMessage();
+      expect(secretRequest).toMatchObject({
+        method: "secrets.resolve",
+        params: {
+          secretRef: "77777777-7777-4777-8777-777777777777",
+          companyId: null,
+        },
+      });
+      writeMessage(stdin, {
+        jsonrpc: "2.0",
+        id: secretRequest.id,
+        result: "global-secret",
+      });
+
+      await expect(nextMessage()).resolves.toMatchObject({
+        id: 2,
+        result: { content: "global-config:global-secret" },
+      });
+    } finally {
+      host.stop();
+      stdin.destroy();
+      stdout.destroy();
+    }
+  });
+});

packages/shared/src/types/plugin.ts

@@ -678,15 +678,17 @@ export interface PluginStateRecord {
 // ---------------------------------------------------------------------------
 
 /**
- * Domain type for a plugin's instance configuration as persisted in the
+ * Domain type for a plugin's configuration as persisted in the
  * `plugin_config` table.
  * See PLUGIN_SPEC.md §21.3 for the schema definition.
  */
 export interface PluginConfig {
   /** UUID primary key. */
   id: string;
-  /** FK to `plugins.id`. Unique — each plugin has at most one config row. */
+  /** FK to `plugins.id`. */
   pluginId: string;
+  /** Company scope for this config row. Null only for legacy/global fallback rows. */
+  companyId: string | null;
   /** Operator-provided configuration values (validated against `instanceConfigSchema`). */
   configJson: Record<string, unknown>;
   /** Most recent config validation error, if any. */

server/src/__tests__/plugin-lifecycle-restart.test.ts

@@ -126,4 +126,35 @@ describe("pluginLifecycleManager.restartWorker", () => {
     expect(started).toHaveBeenCalledTimes(1);
     expect(started).toHaveBeenCalledWith({ pluginId: "plugin-1", pluginKey: "example.plugin" });
   });
+
+  it("uses a late-bound runtime loader after bootstrap wiring completes", async () => {
+    mockRegistry.getById.mockResolvedValue(pluginRecord);
+    mockRegistry.updateStatus.mockResolvedValue(pluginRecord);
+
+    const { handle, workerManager } = makeWorkerManagerStub();
+    let runtimeLoader: Partial<PluginLoader> | undefined;
+    const lifecycle = pluginLifecycleManager(
+      {} as never,
+      {
+        resolveLoader: () => runtimeLoader as PluginLoader | undefined,
+        workerManager,
+      },
+    );
+
+    runtimeLoader = {
+      hasRuntimeServices: vi.fn().mockReturnValue(true) as PluginLoader["hasRuntimeServices"],
+      loadSingle: vi.fn().mockResolvedValue({
+        success: true,
+        plugin: pluginRecord,
+        registered: { worker: true, eventSubscriptions: 0, jobs: 0, webhooks: 0, tools: 0 },
+      }) as PluginLoader["loadSingle"],
+      unloadSingle: vi.fn().mockResolvedValue(undefined) as PluginLoader["unloadSingle"],
+    };
+
+    await lifecycle.restartWorker("plugin-1");
+
+    expect(runtimeLoader.unloadSingle).toHaveBeenCalledWith("plugin-1", "example.plugin");
+    expect(runtimeLoader.loadSingle).toHaveBeenCalledWith("plugin-1");
+    expect(handle.restart).not.toHaveBeenCalled();
+  });
 });

server/src/__tests__/plugin-routes-authz.test.ts

@@ -8,6 +8,11 @@ const mockRegistry = vi.hoisted(() => ({
   upsertConfig: vi.fn(),
   getCompanySettings: vi.fn(),
   upsertCompanySettings: vi.fn(),
+  getConfig: vi.fn(),
+}));
+
+const mockSecrets = vi.hoisted(() => ({
+  syncSecretRefsForTarget: vi.fn(),
 }));
 
 const mockLifecycle = vi.hoisted(() => ({
@@ -22,6 +27,10 @@ vi.mock("../services/plugin-registry.js", () => ({
   pluginRegistryService: () => mockRegistry,
 }));
 
+vi.mock("../services/secrets.js", () => ({
+  secretService: () => mockSecrets,
+}));
+
 vi.mock("../services/plugin-lifecycle.js", () => ({
   pluginLifecycleManager: () => mockLifecycle,
 }));
@@ -327,8 +336,105 @@ describe.sequential("plugin install and upgrade authz", () => {
       });
 
     expect(res.status).toBe(422);
-    expect(res.body.error).toMatch(/secret references are disabled/i);
+    expect(res.body.error).toMatch(/secret references require companyId/i);
     expect(mockRegistry.upsertConfig).not.toHaveBeenCalled();
+    expect(mockSecrets.syncSecretRefsForTarget).not.toHaveBeenCalled();
+  }, 20_000);
+
+  it("saves company-scoped plugin config secret refs as plugin bindings", async () => {
+    readyPlugin();
+    mockRegistry.upsertConfig.mockResolvedValue({
+      id: "99999999-9999-4999-8999-999999999999",
+      pluginId,
+      companyId: companyA,
+      configJson: {
+        apiKeyRef: "77777777-7777-4777-8777-777777777777",
+      },
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const { app } = await createApp(boardActor({
+      isInstanceAdmin: true,
+      companyIds: [companyA],
+    }));
+
+    const res = await request(app)
+      .post(`/api/plugins/${pluginId}/config`)
+      .send({
+        companyId: companyA,
+        configJson: {
+          apiKeyRef: "77777777-7777-4777-8777-777777777777",
+        },
+      });
+
+    expect(res.status).toBe(200);
+    expect(mockSecrets.syncSecretRefsForTarget).toHaveBeenCalledWith(
+      companyA,
+      { targetType: "plugin", targetId: pluginId },
+      [{
+        secretId: "77777777-7777-4777-8777-777777777777",
+        configPath: "$",
+      }],
+    );
+    expect(mockRegistry.upsertConfig).toHaveBeenCalledWith(
+      pluginId,
+      {
+        configJson: {
+          apiKeyRef: "77777777-7777-4777-8777-777777777777",
+        },
+      },
+      companyA,
+    );
+  }, 20_000);
+
+  it("rejects company-scoped plugin config secret refs that do not belong to the selected company", async () => {
+    readyPlugin();
+    mockSecrets.syncSecretRefsForTarget.mockRejectedValueOnce(new Error("Secret not found"));
+
+    const { app } = await createApp(boardActor({
+      isInstanceAdmin: true,
+      companyIds: [companyA],
+    }));
+
+    const res = await request(app)
+      .post(`/api/plugins/${pluginId}/config`)
+      .send({
+        companyId: companyA,
+        configJson: {
+          apiKeyRef: "88888888-8888-4888-8888-888888888888",
+        },
+      });
+
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/secret not found/i);
+    expect(mockRegistry.upsertConfig).not.toHaveBeenCalled();
+  }, 20_000);
+
+  it("reads plugin config from the requested company scope", async () => {
+    readyPlugin();
+    mockRegistry.getConfig.mockResolvedValue({
+      id: "99999999-9999-4999-8999-999999999999",
+      pluginId,
+      companyId: companyA,
+      configJson: { botName: "company-a" },
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const { app } = await createApp(boardActor({
+      isInstanceAdmin: true,
+      companyIds: [companyA, companyB],
+    }));
+
+    const res = await request(app)
+      .get(`/api/plugins/${pluginId}/config?companyId=${companyA}`);
+
+    expect(res.status).toBe(200);
+    expect(mockRegistry.getConfig).toHaveBeenCalledWith(pluginId, companyA);
+    expect(res.body.configJson).toEqual({ botName: "company-a" });
   }, 20_000);
 
   it("allows instance admins to upgrade plugins", async () => {

server/src/__tests__/plugin-secrets-handler-runtime.test.ts

@@ -0,0 +1,105 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getConfig: vi.fn(),
+  resolveSecretValue: vi.fn(),
+}));
+
+vi.mock("../services/plugin-registry.js", () => ({
+  pluginRegistryService: () => ({
+    getConfig: mocks.getConfig,
+  }),
+}));
+
+vi.mock("../services/secrets.js", () => ({
+  secretService: () => ({
+    resolveSecretValue: mocks.resolveSecretValue,
+  }),
+}));
+
+import {
+  createPluginSecretsHandler,
+  PLUGIN_SECRET_REFS_REQUIRE_COMPANY_MESSAGE,
+} from "../services/plugin-secrets-handler.js";
+
+const pluginId = "11111111-1111-4111-8111-111111111111";
+const companyId = "22222222-2222-4222-8222-222222222222";
+const secretRef = "77777777-7777-4777-8777-777777777777";
+
+const manifest = {
+  instanceConfigSchema: {
+    type: "object",
+    properties: {
+      apiKeyRef: {
+        type: "string",
+        format: "secret-ref",
+      },
+    },
+  },
+};
+
+describe("createPluginSecretsHandler runtime company scoping", () => {
+  beforeEach(() => {
+    mocks.getConfig.mockReset();
+    mocks.resolveSecretValue.mockReset();
+  });
+
+  it("fails closed when the runtime call has no company context", async () => {
+    const handler = createPluginSecretsHandler({
+      db: {} as never,
+      pluginId,
+      manifest: manifest as never,
+    });
+
+    await expect(handler.resolve({ secretRef })).rejects.toThrow(
+      PLUGIN_SECRET_REFS_REQUIRE_COMPANY_MESSAGE,
+    );
+    expect(mocks.getConfig).not.toHaveBeenCalled();
+    expect(mocks.resolveSecretValue).not.toHaveBeenCalled();
+  });
+
+  it("rejects a secret ref that is not referenced by that company's plugin config", async () => {
+    mocks.getConfig.mockResolvedValue({
+      configJson: {
+        apiKeyRef: "88888888-8888-4888-8888-888888888888",
+      },
+    });
+
+    const handler = createPluginSecretsHandler({
+      db: {} as never,
+      pluginId,
+      manifest: manifest as never,
+    });
+
+    await expect(handler.resolve({ secretRef, companyId })).rejects.toThrow(
+      /not referenced by this company's plugin config/i,
+    );
+    expect(mocks.getConfig).toHaveBeenCalledWith(pluginId, companyId);
+    expect(mocks.resolveSecretValue).not.toHaveBeenCalled();
+  });
+
+  it("resolves only through the company plugin binding context from saved config", async () => {
+    mocks.getConfig.mockResolvedValue({
+      configJson: {
+        apiKeyRef: secretRef,
+      },
+    });
+    mocks.resolveSecretValue.mockResolvedValue("plaintext-token");
+
+    const handler = createPluginSecretsHandler({
+      db: {} as never,
+      pluginId,
+      manifest: manifest as never,
+    });
+
+    await expect(handler.resolve({ secretRef, companyId })).resolves.toBe("plaintext-token");
+    expect(mocks.resolveSecretValue).toHaveBeenCalledWith(companyId, secretRef, "latest", {
+      consumerType: "plugin",
+      consumerId: pluginId,
+      configPath: "apiKeyRef",
+      actorType: "plugin",
+      actorId: pluginId,
+      pluginId,
+    });
+  });
+});

server/src/__tests__/plugin-secrets-handler.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, it } from "vitest";
 import {
   createPluginSecretsHandler,
-  PLUGIN_SECRET_REFS_DISABLED_MESSAGE,
+  PLUGIN_SECRET_REFS_REQUIRE_COMPANY_MESSAGE,
 } from "../services/plugin-secrets-handler.js";
 
 describe("createPluginSecretsHandler", () => {
-  it("fails closed for plugin secret resolution until company scoping lands", async () => {
+  it("fails closed for plugin secret resolution without company scope", async () => {
     const handler = createPluginSecretsHandler({
       db: {} as never,
       pluginId: "11111111-1111-4111-8111-111111111111",
@@ -13,7 +13,7 @@ describe("createPluginSecretsHandler", () => {
 
     await expect(
       handler.resolve({ secretRef: "77777777-7777-4777-8777-777777777777" }),
-    ).rejects.toThrow(PLUGIN_SECRET_REFS_DISABLED_MESSAGE);
+    ).rejects.toThrow(PLUGIN_SECRET_REFS_REQUIRE_COMPANY_MESSAGE);
   });
 
   it("still rejects malformed secret refs before the feature-disable guard", async () => {

server/src/app.ts

@@ -242,7 +242,11 @@ export async function createApp(
   const eventBus = createPluginEventBus();
   setPluginEventBus(eventBus);
   const jobStore = pluginJobStore(db);
-  const lifecycle = pluginLifecycleManager(db, { workerManager });
+  let loader: ReturnType<typeof pluginLoader>;
+  const lifecycle = pluginLifecycleManager(db, {
+    workerManager,
+    resolveLoader: () => loader,
+  });
   const scheduler = createPluginJobScheduler({
     db,
     jobStore,
@@ -261,7 +265,7 @@ export async function createApp(
   });
   const hostServiceCleanup = createPluginHostServiceCleanup(lifecycle, hostServicesDisposers);
   let viteHtmlRenderer: ReturnType<typeof createCachedViteHtmlRenderer> | null = null;
-  const loader = pluginLoader(
+  loader = pluginLoader(
     db,
     {
       localPluginDir: opts.localPluginDir ?? DEFAULT_LOCAL_PLUGIN_DIR,

server/src/routes/plugins.ts

@@ -75,8 +75,8 @@ import {
 } from "../services/plugin-local-folders.js";
 import {
   extractSecretRefPathsFromConfig,
-  PLUGIN_SECRET_REFS_DISABLED_MESSAGE,
 } from "../services/plugin-secrets-handler.js";
+import { secretService } from "../services/secrets.js";
 import { badRequest, forbidden, notFound, unauthorized, unprocessable } from "../errors.js";
 
 /** UI slot declaration extracted from plugin manifest */
@@ -481,6 +481,7 @@ export function pluginRoutes(
 ) {
   const router = Router();
   const registry = pluginRegistryService(db);
+  const secrets = secretService(db);
   const lifecycle = pluginLifecycleManager(db, {
     loader,
     workerManager: bridgeDeps?.workerManager ?? webhookDeps?.workerManager,
@@ -669,6 +670,27 @@ export function pluginRoutes(
       })));
   }
 
+  function resolvePluginConfigCompanyId(req: Request): string | null {
+    const body = req.body as { companyId?: unknown } | undefined;
+    const rawCompanyId = typeof req.query.companyId === "string"
+      ? req.query.companyId
+      : typeof body?.companyId === "string"
+        ? body.companyId
+        : null;
+
+    if (rawCompanyId) {
+      if (
+        req.actor.type !== "board" ||
+        (req.actor.source !== "local_implicit" && !req.actor.isInstanceAdmin)
+      ) {
+        assertCompanyAccess(req, rawCompanyId);
+      }
+      return rawCompanyId;
+    }
+
+    return null;
+  }
+
   function assertPluginBridgeScope(req: Request, companyId: unknown): string | undefined {
     if (companyId === undefined || companyId === null) {
       assertInstanceAdmin(req);
@@ -2111,7 +2133,8 @@ export function pluginRoutes(
       return;
     }
 
-    const config = await registry.getConfig(plugin.id);
+    const companyId = resolvePluginConfigCompanyId(req);
+    const config = await registry.getConfig(plugin.id, companyId);
     res.json(config);
   });
 
@@ -2141,27 +2164,29 @@ export function pluginRoutes(
       return;
     }
 
-    const body = req.body as { configJson?: Record<string, unknown> } | undefined;
+    const body = req.body as { configJson?: Record<string, unknown>; companyId?: string } | undefined;
     if (!body?.configJson || typeof body.configJson !== "object") {
       res.status(400).json({ error: '"configJson" is required and must be an object' });
       return;
     }
+    const configJson = body.configJson;
+    const companyId = resolvePluginConfigCompanyId(req);
 
     // Strip devUiUrl unless the caller is an instance admin. devUiUrl activates
     // a dev-proxy in the static file route that could be abused for SSRF if any
     // board-level user were allowed to set it.
     if (
-      "devUiUrl" in body.configJson &&
+      "devUiUrl" in configJson &&
       !(req.actor.type === "board" && req.actor.isInstanceAdmin)
     ) {
-      delete body.configJson.devUiUrl;
+      delete configJson.devUiUrl;
     }
 
     // Validate configJson against the plugin's instanceConfigSchema (if declared).
     // This ensures CLI/API callers get the same validation the UI performs client-side.
     const schema = plugin.manifestJson?.instanceConfigSchema;
     if (schema && Object.keys(schema).length > 0) {
-      const validation = validateInstanceConfig(body.configJson, schema);
+      const validation = validateInstanceConfig(configJson, schema);
       if (!validation.valid) {
         res.status(400).json({
           error: "Configuration does not match the plugin's instanceConfigSchema",
@@ -2172,31 +2197,55 @@ export function pluginRoutes(
     }
 
     try {
-      const secretRefsByPath = extractSecretRefPathsFromConfig(body.configJson, schema);
+      const secretRefsByPath = extractSecretRefPathsFromConfig(configJson, schema);
-      if (secretRefsByPath.size > 0) {
+      if (secretRefsByPath.size > 0 && !companyId) {
-        res.status(422).json({ error: PLUGIN_SECRET_REFS_DISABLED_MESSAGE });
+        res.status(422).json({ error: "Plugin secret references require companyId" });
         return;
       }
-
+      const refs = [...secretRefsByPath.entries()].flatMap(([secretId, paths]) =>
-      const result = await registry.upsertConfig(plugin.id, {
+        [...paths].map((configPath) => ({ secretId, configPath })),
-        configJson: body.configJson,
+      );
-      });
+      const persistConfig = async (
+        scopedSecrets: typeof secrets,
+        scopedRegistry: typeof registry,
+        secretDb?: Db,
+      ) => {
+        if (companyId) {
+          const target = { targetType: "plugin" as const, targetId: plugin.id };
+          if (secretDb) {
+            await scopedSecrets.syncSecretRefsForTarget(companyId, target, refs, { db: secretDb });
+          } else {
+            await scopedSecrets.syncSecretRefsForTarget(companyId, target, refs);
+          }
+        }
+        return scopedRegistry.upsertConfig(plugin.id, {
+          configJson,
+        }, companyId);
+      };
+      const result = typeof db.transaction === "function"
+        ? await db.transaction((tx) =>
+          persistConfig(
+            secretService(tx as unknown as Db),
+            pluginRegistryService(tx as unknown as Db),
+            tx as unknown as Db,
+          )
+        )
+        : await persistConfig(secrets, registry);
       await logPluginMutationActivity(req, "plugin.config.updated", plugin.id, {
         pluginId: plugin.id,
         pluginKey: plugin.pluginKey,
-        configKeyCount: Object.keys(body.configJson).length,
+        companyId,
+        configKeyCount: Object.keys(configJson).length,
       });
 
-      // Notify the running worker about the config change (PLUGIN_SPEC §25.4.4).
+      // Only legacy/global config is still pushed into the process-global worker state.
-      // If the worker implements onConfigChanged, send the new config via RPC.
+      // Company-scoped config is read at call time through ctx.config.get().
-      // If it doesn't (METHOD_NOT_IMPLEMENTED), restart the worker so it picks
+      if (companyId === null && bridgeDeps?.workerManager.isRunning(plugin.id)) {
-      // up the new config on re-initialize. If no worker is running, skip.
-      if (bridgeDeps?.workerManager.isRunning(plugin.id)) {
         try {
           await bridgeDeps.workerManager.call(
             plugin.id,
             "configChanged",
-            { config: body.configJson },
+            { config: configJson },
           );
         } catch (rpcErr) {
           if (

server/src/services/plugin-host-services.ts

@@ -489,7 +489,7 @@ export function buildHostServices(
   const registry = pluginRegistryService(db);
   const stateStore = pluginStateStore(db);
   const pluginDb = pluginDatabaseService(db);
-  const secretsHandler = createPluginSecretsHandler({ db, pluginId });
+  const secretsHandler = createPluginSecretsHandler({ db, pluginId, manifest: options.manifest });
   const companies = companyService(db);
   const agents = agentService(db);
   const managedAgents = pluginManagedAgentService(db, {
@@ -1053,8 +1053,8 @@ export function buildHostServices(
 
   return {
     config: {
-      async get() {
+      async get(params) {
-        const configRow = await registry.getConfig(pluginId);
+        const configRow = await registry.getConfig(pluginId, params?.companyId ?? null);
         return configRow?.configJson ?? {};
       },
     },

server/src/services/plugin-lifecycle.ts

@@ -267,6 +267,8 @@ export interface PluginLifecycleManager {
 export interface PluginLifecycleManagerOptions {
   /** Plugin loader instance. Falls back to the default if omitted. */
   loader?: PluginLoader;
+  /** Resolve the loader lazily for bootstrap paths with circular wiring. */
+  resolveLoader?: () => PluginLoader | undefined;
 
   /**
    * Worker process manager. When provided, lifecycle transitions that bring
@@ -308,6 +310,7 @@ export function pluginLifecycleManager(
   // Support the legacy signature: pluginLifecycleManager(db, loader)
   // as well as the new options object form.
   let loaderArg: PluginLoader | undefined;
+  let resolveLoader: (() => PluginLoader | undefined) | undefined;
   let workerManager: PluginWorkerManager | undefined;
 
   if (options && typeof options === "object" && "discoverAll" in options) {
@@ -316,11 +319,12 @@ export function pluginLifecycleManager(
   } else if (options && typeof options === "object") {
     const opts = options as PluginLifecycleManagerOptions;
     loaderArg = opts.loader;
+    resolveLoader = opts.resolveLoader;
     workerManager = opts.workerManager;
   }
 
   const registry = pluginRegistryService(db);
-  const pluginLoaderInstance = loaderArg ?? pluginLoader(db);
+  const fallbackLoader = loaderArg ?? pluginLoader(db);
   const emitter = new EventEmitter();
   emitter.setMaxListeners(100); // plugins may have many listeners; 100 is a safe upper bound
 
@@ -386,6 +390,10 @@ export function pluginLifecycleManager(
     emitter.emit(event, payload);
   }
 
+  function currentLoader(): PluginLoader {
+    return resolveLoader?.() ?? loaderArg ?? fallbackLoader;
+  }
+
   // -----------------------------------------------------------------------
   // Worker management helpers
   // -----------------------------------------------------------------------
@@ -415,14 +423,15 @@ export function pluginLifecycleManager(
   }
 
   async function activateReadyPlugin(pluginId: string): Promise<void> {
+    const loader = currentLoader();
     const supportsRuntimeActivation =
-      typeof pluginLoaderInstance.hasRuntimeServices === "function"
+      typeof loader.hasRuntimeServices === "function"
-      && typeof pluginLoaderInstance.loadSingle === "function";
+      && typeof loader.loadSingle === "function";
-    if (!supportsRuntimeActivation || !pluginLoaderInstance.hasRuntimeServices()) {
+    if (!supportsRuntimeActivation || !loader.hasRuntimeServices()) {
       return;
     }
 
-    const loadResult = await pluginLoaderInstance.loadSingle(pluginId);
+    const loadResult = await loader.loadSingle(pluginId);
     if (!loadResult.success) {
       throw new Error(
         loadResult.error
@@ -435,12 +444,13 @@ export function pluginLifecycleManager(
     pluginId: string,
     pluginKey: string,
   ): Promise<void> {
+    const loader = currentLoader();
     const supportsRuntimeDeactivation =
-      typeof pluginLoaderInstance.hasRuntimeServices === "function"
+      typeof loader.hasRuntimeServices === "function"
-      && typeof pluginLoaderInstance.unloadSingle === "function";
+      && typeof loader.unloadSingle === "function";
 
-    if (supportsRuntimeDeactivation && pluginLoaderInstance.hasRuntimeServices()) {
+    if (supportsRuntimeDeactivation && loader.hasRuntimeServices()) {
-      await pluginLoaderInstance.unloadSingle(pluginId, pluginKey);
+      await loader.unloadSingle(pluginId, pluginKey);
       return;
     }
 
@@ -541,7 +551,7 @@ export function pluginLifecycleManager(
       // If already uninstalled and removeData, hard-delete
       if (plugin.status === "uninstalled") {
         if (removeData) {
-          await pluginLoaderInstance.cleanupInstallArtifacts(plugin);
+          await currentLoader().cleanupInstallArtifacts(plugin);
           const deleted = await registry.uninstall(pluginId, true);
           log.info(
             { pluginId, pluginKey: plugin.pluginKey },
@@ -561,7 +571,7 @@ export function pluginLifecycleManager(
       }
 
       await deactivatePluginRuntime(pluginId, plugin.pluginKey);
-      await pluginLoaderInstance.cleanupInstallArtifacts(plugin);
+      await currentLoader().cleanupInstallArtifacts(plugin);
 
       // Perform the uninstall via registry (handles soft/hard delete)
       const result = await registry.uninstall(pluginId, removeData);
@@ -656,7 +666,7 @@ export function pluginLifecycleManager(
 
       // 1. Download and validate new package via loader
       const { oldManifest, newManifest, discovered } =
-        await pluginLoaderInstance.upgradePlugin(pluginId, { version });
+        await currentLoader().upgradePlugin(pluginId, { version });
 
       log.info(
         {
@@ -777,10 +787,10 @@ export function pluginLifecycleManager(
       }
 
       const supportsRuntimeActivation =
-        typeof pluginLoaderInstance.hasRuntimeServices === "function"
+        typeof currentLoader().hasRuntimeServices === "function"
-        && typeof pluginLoaderInstance.loadSingle === "function"
+        && typeof currentLoader().loadSingle === "function"
-        && typeof pluginLoaderInstance.unloadSingle === "function"
+        && typeof currentLoader().unloadSingle === "function"
-        && pluginLoaderInstance.hasRuntimeServices();
+        && currentLoader().hasRuntimeServices();
 
       if (supportsRuntimeActivation) {
         log.info(

server/src/services/plugin-registry.ts

@@ -1,4 +1,4 @@
-import { asc, eq, ne, sql, and } from "drizzle-orm";
+import { asc, eq, ne, sql, and, isNull } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
   plugins,
@@ -44,6 +44,13 @@ function isPluginKeyConflict(error: unknown): boolean {
   return err.code === "23505" && constraint === "plugins_plugin_key_idx";
 }
 
+function pluginConfigExactScopeCondition(pluginId: string, companyId?: string | null) {
+  return and(
+    eq(pluginConfig.pluginId, pluginId),
+    companyId ? eq(pluginConfig.companyId, companyId) : isNull(pluginConfig.companyId),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Service
 // ---------------------------------------------------------------------------
@@ -280,27 +287,37 @@ export function pluginRegistryService(db: Db) {
 
     // ----- Config ---------------------------------------------------------
 
-    /** Retrieve a plugin's instance configuration. */
+    /** Retrieve a plugin's company-scoped config, or the legacy global fallback. */
-    getConfig: (pluginId: string) =>
+    getConfig: async (pluginId: string, companyId?: string | null) => {
-      db
+      if (companyId) {
+        const scoped = await db
+          .select()
+          .from(pluginConfig)
+          .where(pluginConfigExactScopeCondition(pluginId, companyId))
+          .then((rows) => rows[0] ?? null);
+        if (scoped) return scoped;
+      }
+
+      return db
         .select()
         .from(pluginConfig)
-        .where(eq(pluginConfig.pluginId, pluginId))
+        .where(pluginConfigExactScopeCondition(pluginId, null))
-        .then((rows) => rows[0] ?? null),
+        .then((rows) => rows[0] ?? null);
+    },
 
     /**
      * Create or fully replace a plugin's instance configuration.
      * If a config row already exists for the plugin it is replaced;
      * otherwise a new row is inserted.
      */
-    upsertConfig: async (pluginId: string, input: UpsertPluginConfig) => {
+    upsertConfig: async (pluginId: string, input: UpsertPluginConfig, companyId?: string | null) => {
       const plugin = await getById(pluginId);
       if (!plugin) throw notFound("Plugin not found");
 
       const existing = await db
         .select()
         .from(pluginConfig)
-        .where(eq(pluginConfig.pluginId, pluginId))
+        .where(pluginConfigExactScopeCondition(pluginId, companyId))
         .then((rows) => rows[0] ?? null);
 
       if (existing) {
@@ -311,7 +328,7 @@ export function pluginRegistryService(db: Db) {
             lastError: null,
             updatedAt: new Date(),
           })
-          .where(eq(pluginConfig.pluginId, pluginId))
+          .where(pluginConfigExactScopeCondition(pluginId, companyId))
           .returning()
           .then((rows) => rows[0]);
       }
@@ -320,6 +337,7 @@ export function pluginRegistryService(db: Db) {
         .insert(pluginConfig)
         .values({
           pluginId,
+          companyId: companyId ?? null,
           configJson: input.configJson,
         })
         .returning()
@@ -330,14 +348,14 @@ export function pluginRegistryService(db: Db) {
      * Partially update a plugin's instance configuration via shallow merge.
      * If no config row exists yet one is created with the supplied values.
      */
-    patchConfig: async (pluginId: string, input: PatchPluginConfig) => {
+    patchConfig: async (pluginId: string, input: PatchPluginConfig, companyId?: string | null) => {
       const plugin = await getById(pluginId);
       if (!plugin) throw notFound("Plugin not found");
 
       const existing = await db
         .select()
         .from(pluginConfig)
-        .where(eq(pluginConfig.pluginId, pluginId))
+        .where(pluginConfigExactScopeCondition(pluginId, companyId))
         .then((rows) => rows[0] ?? null);
 
       if (existing) {
@@ -349,7 +367,7 @@ export function pluginRegistryService(db: Db) {
             lastError: null,
             updatedAt: new Date(),
           })
-          .where(eq(pluginConfig.pluginId, pluginId))
+          .where(pluginConfigExactScopeCondition(pluginId, companyId))
           .returning()
           .then((rows) => rows[0]);
       }
@@ -358,6 +376,7 @@ export function pluginRegistryService(db: Db) {
         .insert(pluginConfig)
         .values({
           pluginId,
+          companyId: companyId ?? null,
           configJson: input.configJson,
         })
         .returning()
@@ -368,11 +387,11 @@ export function pluginRegistryService(db: Db) {
      * Record an error against a plugin's config (e.g. validation failure
      * against the plugin's instanceConfigSchema).
      */
-    setConfigError: async (pluginId: string, lastError: string | null) => {
+    setConfigError: async (pluginId: string, lastError: string | null, companyId?: string | null) => {
       const rows = await db
         .update(pluginConfig)
         .set({ lastError, updatedAt: new Date() })
-        .where(eq(pluginConfig.pluginId, pluginId))
+        .where(pluginConfigExactScopeCondition(pluginId, companyId))
         .returning();
 
       if (rows.length === 0) throw notFound("Plugin config not found");
@@ -380,10 +399,10 @@ export function pluginRegistryService(db: Db) {
     },
 
     /** Delete a plugin's config row. */
-    deleteConfig: async (pluginId: string) => {
+    deleteConfig: async (pluginId: string, companyId?: string | null) => {
       const rows = await db
         .delete(pluginConfig)
-        .where(eq(pluginConfig.pluginId, pluginId))
+        .where(pluginConfigExactScopeCondition(pluginId, companyId))
         .returning();
 
       return rows[0] ?? null;

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

@@ -34,14 +34,17 @@
  */
 
 import type { Db } from "@paperclipai/db";
+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
 import {
   collectSecretRefPaths,
   isUuidSecretRef,
   readConfigValueAtPath,
 } from "./json-schema-secret-refs.js";
+import { pluginRegistryService } from "./plugin-registry.js";
+import { secretService } from "./secrets.js";
 
-export const PLUGIN_SECRET_REFS_DISABLED_MESSAGE =
+export const PLUGIN_SECRET_REFS_REQUIRE_COMPANY_MESSAGE =
-  "Plugin secret references are disabled until company-scoped plugin config lands";
+  "Plugin secret references require an active company-scoped runtime context";
 
 // ---------------------------------------------------------------------------
 // Error helpers
@@ -125,6 +128,8 @@ export function extractSecretRefPathsFromConfig(
 export interface PluginSecretsResolveParams {
   /** The secret reference string (a secret UUID). */
   secretRef: string;
+  /** The company whose scoped plugin config is active for this invocation. */
+  companyId?: string | null;
 }
 
 /**
@@ -139,6 +144,8 @@ export interface PluginSecretsHandlerOptions {
    * that reach the plugin worker.
    */
   pluginId: string;
+  /** Plugin manifest, used to extract schema-declared secret-ref paths. */
+  manifest?: PaperclipPluginManifestV1 | null;
 }
 
 /**
@@ -199,24 +206,17 @@ function createRateLimiter(maxAttempts: number, windowMs: number) {
 export function createPluginSecretsHandler(
   options: PluginSecretsHandlerOptions,
 ): PluginSecretsService {
-  const { pluginId } = options;
+  const { pluginId, manifest } = options;
+  const registry = pluginRegistryService(options.db);
+  const secrets = secretService(options.db);
 
-  // Rate limit: max 30 resolution attempts per plugin per minute
+  // Rate limit: max 30 resolution attempts per plugin+company per minute.
   const rateLimiter = createRateLimiter(30, 60_000);
 
   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
       // ---------------------------------------------------------------
@@ -230,9 +230,41 @@ export function createPluginSecretsHandler(
         throw invalidSecretRef(trimmedRef);
       }
 
-      // Fail closed until plugin config and worker runtime both carry an
+      const companyId = typeof params.companyId === "string" ? params.companyId.trim() : "";
-      // explicit company scope for secret bindings and resolution.
+      const rateLimitKey = `${pluginId}:${companyId || "__no_company__"}`;
-      throw new Error(PLUGIN_SECRET_REFS_DISABLED_MESSAGE);
+      if (!rateLimiter.check(rateLimitKey)) {
+        const err = new Error("Rate limit exceeded for secret resolution");
+        err.name = "RateLimitExceededError";
+        throw err;
+      }
+
+      if (!companyId) {
+        throw new Error(PLUGIN_SECRET_REFS_REQUIRE_COMPANY_MESSAGE);
+      }
+
+      const configRow = await registry.getConfig(pluginId, companyId);
+      const refsBySecret = extractSecretRefPathsFromConfig(
+        configRow?.configJson ?? {},
+        manifest?.instanceConfigSchema,
+      );
+      const paths = [...(refsBySecret.get(trimmedRef) ?? [])];
+      if (paths.length === 0) {
+        throw new Error("Secret is not referenced by this company's plugin config");
+      }
+      if (paths.length > 1) {
+        throw new Error(
+          `Secret reference is ambiguous in this company's plugin config at: ${paths.join(", ")}`,
+        );
+      }
+
+      return secrets.resolveSecretValue(companyId, trimmedRef, "latest", {
+        consumerType: "plugin",
+        consumerId: pluginId,
+        configPath: paths[0],
+        actorType: "plugin",
+        actorId: pluginId,
+        pluginId,
+      });
     },
   };
 }

server/src/services/secrets.ts

@@ -2034,6 +2034,7 @@ export function secretService(db: Db) {
         required?: boolean;
         label?: string | null;
       }>,
+      options?: { db?: SecretBindingDb },
     ) => {
       const normalizedRefs: Array<{
         secretId: string;
@@ -2042,8 +2043,9 @@ export function secretService(db: Db) {
         required: boolean;
         label: string | null;
       }> = [];
+      const bindingDb = options?.db ?? db;
       for (const ref of refs) {
-        await assertSecretInCompany(companyId, ref.secretId);
+        await assertSecretInCompany(companyId, ref.secretId, bindingDb);
         normalizedRefs.push({
           secretId: ref.secretId,
           configPath: ref.configPath,
@@ -2055,10 +2057,10 @@ export function secretService(db: Db) {
 
       const pathPrefixes = [...new Set(normalizedRefs.map((ref) => ref.configPath.split(".")[0]))];
 
-      await db.transaction(async (tx) => {
+      const writeBindings = async (targetDb: SecretBindingDb) => {
         if (pathPrefixes.length > 0) {
           for (const pathPrefix of pathPrefixes) {
-            await tx
+            await targetDb
               .delete(companySecretBindings)
               .where(
                 and(
@@ -2070,7 +2072,7 @@ export function secretService(db: Db) {
               );
           }
         } else {
-          await tx
+          await targetDb
             .delete(companySecretBindings)
             .where(
               and(
@@ -2081,7 +2083,7 @@ export function secretService(db: Db) {
             );
         }
         if (normalizedRefs.length === 0) return;
-        await tx.insert(companySecretBindings).values(
+        await targetDb.insert(companySecretBindings).values(
           normalizedRefs.map((ref) => ({
             companyId,
             secretId: ref.secretId,
@@ -2093,7 +2095,13 @@ export function secretService(db: Db) {
             label: ref.label,
           })),
         );
-      });
+      };
+
+      if (options?.db) {
+        await writeBindings(options.db);
+      } else {
+        await db.transaction(async (tx) => writeBindings(tx));
+      }
       return normalizedRefs;
     },
 

ui/src/api/plugins.ts

@@ -357,8 +357,10 @@ export const pluginsApi = {
    *
    * @param pluginId - UUID of the plugin.
    */
-  getConfig: (pluginId: string) =>
+  getConfig: (pluginId: string, companyId?: string | null) => {
-    api.get<PluginConfig | null>(`/plugins/${pluginId}/config`),
+    const qs = companyId ? `?companyId=${encodeURIComponent(companyId)}` : "";
+    return api.get<PluginConfig | null>(`/plugins/${pluginId}/config${qs}`);
+  },
 
   /**
    * Save (create or update) the configuration for a plugin.
@@ -369,8 +371,8 @@ export const pluginsApi = {
    * @param pluginId - UUID of the plugin.
    * @param configJson - Configuration values matching the plugin's `instanceConfigSchema`.
    */
-  saveConfig: (pluginId: string, configJson: Record<string, unknown>) =>
+  saveConfig: (pluginId: string, configJson: Record<string, unknown>, companyId?: string | null) =>
-    api.post<PluginConfig>(`/plugins/${pluginId}/config`, { configJson }),
+    api.post<PluginConfig>(`/plugins/${pluginId}/config`, { configJson, companyId }),
 
   /**
    * Call the plugin's `validateConfig` RPC method to test the configuration

ui/src/lib/queryKeys.ts

@@ -199,7 +199,8 @@ export const queryKeys = {
     detail: (pluginId: string) => ["plugins", pluginId] as const,
     health: (pluginId: string) => ["plugins", pluginId, "health"] as const,
     uiContributions: ["plugins", "ui-contributions"] as const,
-    config: (pluginId: string) => ["plugins", pluginId, "config"] as const,
+    config: (pluginId: string, companyId?: string | null) =>
+      ["plugins", pluginId, "config", companyId ?? null] as const,
     localFolders: (pluginId: string, companyId: string) =>
       ["plugins", pluginId, "companies", companyId, "local-folders"] as const,
     dashboard: (pluginId: string) => ["plugins", pluginId, "dashboard"] as const,

ui/src/pages/PluginSettings.tsx

@@ -47,8 +47,8 @@ import {
  * - `GET /api/plugins/:pluginId/health` — health diagnostics (polling).
  *   Only fetched when `plugin.status === "ready"`.
  * - `GET /api/plugins/:pluginId/dashboard` — aggregated runtime dashboard data (polling).
- * - `GET /api/plugins/:pluginId/config` — current config values.
+ * - `GET /api/plugins/:pluginId/config?companyId=...` — current company config values.
- * - `POST /api/plugins/:pluginId/config` — save config values.
+ * - `POST /api/plugins/:pluginId/config` — save company config values.
  * - `POST /api/plugins/:pluginId/config/test` — test configuration.
  *
  * URL params:
@@ -97,9 +97,9 @@ export function PluginSettings() {
   const hasConfigSchema = configSchema && configSchema.properties && Object.keys(configSchema.properties).length > 0;
 
   const { data: configData, isLoading: configLoading } = useQuery({
-    queryKey: queryKeys.plugins.config(pluginId!),
+    queryKey: queryKeys.plugins.config(pluginId!, selectedCompanyId),
-    queryFn: () => pluginsApi.getConfig(pluginId!),
+    queryFn: () => pluginsApi.getConfig(pluginId!, selectedCompanyId),
-    enabled: !!pluginId && !!hasConfigSchema,
+    enabled: !!pluginId && !!hasConfigSchema && !!selectedCompanyId,
   });
 
   const { slots } = usePluginSlots({
@@ -245,6 +245,7 @@ export function PluginSettings() {
               ) : hasConfigSchema ? (
                 <PluginConfigForm
                   pluginId={pluginId!}
+                  companyId={selectedCompanyId}
                   schema={configSchema!}
                   initialValues={configData?.configJson}
                   isLoading={configLoading}
@@ -919,6 +920,7 @@ function isLikelyAbsolutePath(pathValue: string) {
 
 interface PluginConfigFormProps {
   pluginId: string;
+  companyId?: string | null;
   schema: JsonSchemaNode;
   initialValues?: Record<string, unknown>;
   isLoading?: boolean;
@@ -935,7 +937,7 @@ interface PluginConfigFormProps {
  * Separated from PluginSettings to isolate re-render scope — only the form
  * re-renders on field changes, not the entire page.
  */
-function PluginConfigForm({ pluginId, schema, initialValues, isLoading, pluginStatus, supportsConfigTest }: PluginConfigFormProps) {
+function PluginConfigForm({ pluginId, companyId, schema, initialValues, isLoading, pluginStatus, supportsConfigTest }: PluginConfigFormProps) {
   const queryClient = useQueryClient();
 
   // Form values: start with saved values, fall back to schema defaults
@@ -971,11 +973,11 @@ function PluginConfigForm({ pluginId, schema, initialValues, isLoading, pluginSt
   // Save mutation
   const saveMutation = useMutation({
     mutationFn: (configJson: Record<string, unknown>) =>
-      pluginsApi.saveConfig(pluginId, configJson),
+      pluginsApi.saveConfig(pluginId, configJson, companyId),
     onSuccess: () => {
       setSaveMessage({ type: "success", text: "Configuration saved." });
       setTestResult(null);
-      queryClient.invalidateQueries({ queryKey: queryKeys.plugins.config(pluginId) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.plugins.config(pluginId, companyId) });
       // Clear success message after 3s
       setTimeout(() => setSaveMessage(null), 3000);
     },