@vellumai/assistant 0.10.9-dev.202607161044.1a55a2d → 0.10.9-dev.202607161241.f69e16e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.9-dev.202607161044.1a55a2d",
+  "version": "0.10.9-dev.202607161241.f69e16e",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/credential-security-invariants.test.ts

@@ -231,6 +231,7 @@ describe("Invariant 2: no generic plaintext secret read API", () => {
       "tools/network/web-fetch.ts", // Firecrawl /scrape BYOK fetch provider API key lookup (firecrawl provider key)
       "workspace/default-provider-ensure.ts", // legacy anthropic echo disambiguation (vault key presence check)
       "providers/inference/connection-availability.ts", // shared (provider, connection) availability status (credential presence check only; value never leaves the helper)
+      "plugin-api/resolve-credential.ts", // plugin-facing resolveCredential — reveal-equivalent plaintext read, scoped to the in-context plugin's own field
     ]);
 
     const thisDir = dirname(fileURLToPath(import.meta.url));

package/src/__tests__/plugin-api-resolve-credential.test.ts

@@ -0,0 +1,140 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  spyOn,
+  test,
+} from "bun:test";
+
+import { credentialKey } from "@vellumai/credential-storage";
+
+import {
+  CredentialResolutionError,
+  resolveCredential,
+} from "../plugin-api/resolve-credential.js";
+import { runInPluginContext } from "../plugins/plugin-execution-context.js";
+import * as secureKeys from "../security/secure-keys.js";
+import {
+  _setMetadataPath,
+  upsertCredentialMetadata,
+} from "../tools/credentials/metadata-store.js";
+
+// Real metadata store backed by a temp file (no module mocking — a mock.module
+// on metadata-store / secure-keys would replace the whole module namespace and
+// leak into other test files in the same process). Only the secure backend read
+// is intercepted, via a restorable spy.
+
+const TEST_DIR = join(
+  tmpdir(),
+  `vellum-plugin-resolvecred-${randomBytes(4).toString("hex")}`,
+);
+const META_PATH = join(TEST_DIR, "metadata.json");
+
+let secureStore: Map<string, string>;
+let unreachable: boolean;
+let getSpy: ReturnType<typeof spyOn>;
+
+function seedCredential(service: string, field: string, value: string): string {
+  const meta = upsertCredentialMetadata(service, field, {});
+  secureStore.set(credentialKey(service, field), value);
+  return meta.credentialId;
+}
+
+beforeEach(() => {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true });
+  }
+  mkdirSync(TEST_DIR, { recursive: true });
+  _setMetadataPath(META_PATH);
+
+  secureStore = new Map();
+  unreachable = false;
+  getSpy = spyOn(secureKeys, "getSecureKeyResultAsync").mockImplementation(
+    async (key: string) => ({
+      value: secureStore.get(key),
+      unreachable: unreachable && !secureStore.has(key),
+    }),
+  );
+});
+
+afterEach(() => {
+  getSpy.mockRestore();
+});
+
+afterAll(() => {
+  _setMetadataPath(null);
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true });
+  }
+});
+
+describe("resolveCredential", () => {
+  test("resolves plaintext by service/field ref when no plugin is in context", async () => {
+    seedCredential("openai", "api_key", "sk-secret");
+    await expect(resolveCredential("openai/api_key")).resolves.toBe(
+      "sk-secret",
+    );
+  });
+
+  test("resolves plaintext by credential UUID", async () => {
+    const id = seedCredential("stripe", "acme", "stripe-secret");
+    await expect(resolveCredential(id)).resolves.toBe("stripe-secret");
+  });
+
+  test("throws not found for an unknown ref", async () => {
+    await expect(resolveCredential("nope/missing")).rejects.toBeInstanceOf(
+      CredentialResolutionError,
+    );
+  });
+
+  test("throws when the store is unreachable", async () => {
+    upsertCredentialMetadata("openai", "api_key", {});
+    unreachable = true;
+    await expect(resolveCredential("openai/api_key")).rejects.toThrow(
+      /unreachable/,
+    );
+  });
+
+  describe("plugin scoping", () => {
+    test("allows a plugin to resolve a credential whose field matches its name", async () => {
+      seedCredential("openai", "acme", "scoped-secret");
+      const value = await runInPluginContext("acme", () =>
+        resolveCredential("openai/acme"),
+      );
+      expect(value).toBe("scoped-secret");
+    });
+
+    test("blocks a plugin from resolving a credential whose field differs from its name", async () => {
+      seedCredential("openai", "api_key", "sk-secret");
+      await expect(
+        runInPluginContext("acme", () => resolveCredential("openai/api_key")),
+      ).rejects.toThrow(/out of scope/);
+    });
+
+    test("does not read the secure backend when out of scope", async () => {
+      seedCredential("openai", "api_key", "sk-secret");
+      getSpy.mockClear();
+      await expect(
+        runInPluginContext("acme", () => resolveCredential("openai/api_key")),
+      ).rejects.toThrow(CredentialResolutionError);
+      expect(getSpy).not.toHaveBeenCalled();
+    });
+
+    test("scoping applies by field only, across any service", async () => {
+      seedCredential("stripe", "acme", "stripe-secret");
+      seedCredential("openai", "acme", "openai-secret");
+      await expect(
+        runInPluginContext("acme", () => resolveCredential("stripe/acme")),
+      ).resolves.toBe("stripe-secret");
+      await expect(
+        runInPluginContext("acme", () => resolveCredential("openai/acme")),
+      ).resolves.toBe("openai-secret");
+    });
+  });
+});

package/src/plugin-api/index.ts

@@ -150,6 +150,16 @@ export { getModelProfiles } from "./model-profiles.js";
 // looks up the model catalog's `supportsVision` flag (mix profiles are
 // vision-capable if any arm is). Returns false when nothing resolves.
 export { doesSupportVision } from "./vision-support.js";
+// Resolve a stored credential to its plaintext value — the same value
+// `assistant credentials reveal` prints — from a UUID or a "service/field"
+// reference. When a plugin is in context, resolution is scoped to credentials
+// whose `field` matches the plugin's manifest name; outside any plugin it is
+// unscoped. Throws CredentialResolutionError when the ref does not resolve, the
+// store is unreachable, or the credential is out of the plugin's scope.
+export {
+  CredentialResolutionError,
+  resolveCredential,
+} from "./resolve-credential.js";
 // Resolve a provider for a call site (optionally overriding the profile) so a
 // plugin can run inference through the workspace's configured profiles and
 // credentials — managed-proxy or BYOK — without supplying its own API key.

package/src/plugin-api/resolve-credential.ts

@@ -0,0 +1,75 @@
+/**
+ * Plugin-facing credential resolution.
+ *
+ * {@link resolveCredential} returns a stored credential's plaintext value — the
+ * same value `assistant credentials reveal` prints — resolving a reference that
+ * is either a credential UUID or a `"service/field"` string, exactly as the
+ * reveal path does (see {@link ../tools/credentials/resolve.resolveCredentialRef}
+ * and the `credentials/reveal` route).
+ *
+ * ## Plugin scoping
+ *
+ * When a plugin is in context — its hook or tool is executing, tracked by
+ * {@link ../plugins/plugin-execution-context.getCurrentPluginName} — resolution
+ * is restricted: the plugin may only resolve credentials whose `field` equals
+ * the plugin's own manifest name. A plugin named `acme` can therefore read
+ * `openai/acme` or `stripe/acme` but not `openai/api_key`. Outside any plugin
+ * context (host-internal callers, CLI, tests) the resolver is unscoped and
+ * behaves like a direct reveal.
+ */
+
+import { getCurrentPluginName } from "../plugins/plugin-execution-context.js";
+import { getSecureKeyResultAsync } from "../security/secure-keys.js";
+import { resolveCredentialRef } from "../tools/credentials/resolve.js";
+
+/**
+ * Raised when a credential cannot be resolved: the reference does not match a
+ * stored credential, the store is unreachable, or the calling plugin is not
+ * permitted to resolve the requested credential.
+ */
+export class CredentialResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialResolutionError";
+  }
+}
+
+/**
+ * Resolve a credential reference to its plaintext value.
+ *
+ * @param ref A credential UUID or a `"service/field"` string.
+ * @returns The plaintext credential value.
+ * @throws {CredentialResolutionError} when the reference does not resolve, the
+ *   store is unreachable, or a plugin in context is not scoped to the credential.
+ */
+export async function resolveCredential(ref: string): Promise<string> {
+  const resolved = resolveCredentialRef(ref);
+  if (!resolved) {
+    throw new CredentialResolutionError(`Credential not found: ${ref}`);
+  }
+
+  // Scope the resolution to the plugin in context, if any. The field-name gate
+  // is enforced before the plaintext is read so an out-of-scope plugin never
+  // touches the secure backend.
+  const pluginName = getCurrentPluginName();
+  if (pluginName !== undefined && resolved.field !== pluginName) {
+    throw new CredentialResolutionError(
+      `Plugin "${pluginName}" may only resolve credentials whose field matches its name; ` +
+        `"${resolved.service}/${resolved.field}" is out of scope.`,
+    );
+  }
+
+  const { value, unreachable } = await getSecureKeyResultAsync(
+    resolved.storageKey,
+  );
+  if (value == null || value.length === 0) {
+    if (unreachable) {
+      throw new CredentialResolutionError(
+        "Credential store is unreachable — ensure the assistant is running",
+      );
+    }
+    throw new CredentialResolutionError(`Credential not found: ${ref}`);
+  }
+
+  return value;
+}

package/src/plugins/pipeline.ts

@@ -25,6 +25,7 @@ import { getHookEntriesFor } from "../hooks/registry.js";
 import type { BaseHookContext } from "../hooks/types.js";
 import { type HookName, HOOKS } from "../plugin-api/constants.js";
 import { getLogger } from "../util/logger.js";
+import { runInPluginContext } from "./plugin-execution-context.js";
 import type { HookEntry } from "./types.js";
 
 // ─── Hook runner ────────────────────────────────────────────────────────────
@@ -352,8 +353,15 @@ export async function runHook<TInput extends object>(
       broadcast: makeHookBroadcast({ conversationId, hookName: name, owner }),
     };
     try {
+      // Mark the contributing plugin as in context so host APIs the hook
+      // reaches (e.g. resolveCredential) can scope to it. Standalone workspace
+      // hooks are not plugins and establish no context.
+      const invokeHook =
+        owner.kind === "plugin"
+          ? () => runInPluginContext(owner.id, () => fn(draft))
+          : () => fn(draft);
       const result = await callWithTimeout(
-        () => fn(draft),
+        invokeHook,
         HOOK_TIMEOUT_MS,
         `plugin hook '${name}' (${owner.id}) timed out after ${HOOK_TIMEOUT_MS}ms`,
       );

package/src/plugins/plugin-execution-context.ts

@@ -0,0 +1,44 @@
+/**
+ * Plugin execution context — tracks which plugin's code is currently running.
+ *
+ * Host APIs exposed to plugins through `@vellumai/plugin-api` sometimes need to
+ * know *which* plugin is calling them so they can scope their behavior to that
+ * plugin (e.g. {@link ../plugin-api/resolve-credential.resolveCredential} limits
+ * a plugin to its own credentials). A plugin's manifest name is not threaded
+ * through every host call, so the pipeline that invokes a plugin's hook — and
+ * the tool executor that runs a plugin's tool — mark the plugin as "in context"
+ * for the duration of that invocation via an {@link AsyncLocalStorage}. Host
+ * APIs read {@link getCurrentPluginName} to recover it.
+ *
+ * The store propagates across `await` boundaries, so a plugin that awaits a
+ * host API deep inside its hook/tool body is still seen as in context. When no
+ * plugin is in context (host-internal callers, the CLI, tests), the store is
+ * empty and scoped APIs fall back to their unscoped behavior.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface PluginExecutionContext {
+  /** Manifest name of the plugin whose hook or tool is currently executing. */
+  pluginName: string;
+}
+
+const storage = new AsyncLocalStorage<PluginExecutionContext>();
+
+/**
+ * Run `fn` with `pluginName` marked as the plugin currently in context. The
+ * returned value (including a promise) carries the context across its async
+ * continuations, so callers pass the promise straight to a timeout wrapper
+ * without losing the binding.
+ */
+export function runInPluginContext<T>(pluginName: string, fn: () => T): T {
+  return storage.run({ pluginName }, fn);
+}
+
+/**
+ * Name of the plugin whose hook or tool is currently executing, or `undefined`
+ * when no plugin is in context.
+ */
+export function getCurrentPluginName(): string | undefined {
+  return storage.getStore()?.pluginName;
+}

package/src/runtime/routes/__tests__/migration-vellum-metadata-reconcile.test.ts

@@ -28,6 +28,7 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { credentialKey } from "../../../security/credential-key.js";
+import * as actualMetadataStore from "../../../tools/credentials/metadata-store.js";
 
 type MetadataRecord = {
   credentialId: string;
@@ -80,7 +81,13 @@ mock.module("../../../security/secure-keys.js", () => ({
   _resetBackend: () => {},
 }));
 
+// Spread the real module so every export the reconcile handler's transitive
+// graph links (e.g. getCredentialMetadataById, listCredentialMetadata pulled in
+// via the plugin-api hub) stays present; only the two functions under test are
+// overridden. A partial mock replaces the whole namespace and fails to link the
+// unlisted exports.
 mock.module("../../../tools/credentials/metadata-store.js", () => ({
+  ...actualMetadataStore,
   getCredentialMetadata: (service: string, field: string) =>
     metadataStore.get(`${service}:${field}`),
   upsertCredentialMetadata: (

package/src/tools/executor.ts

@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { getConfig } from "../config/loader.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
 import { RiskLevel } from "../permissions/types.js";
+import { runInPluginContext } from "../plugins/plugin-execution-context.js";
 import { TokenExpiredError } from "../security/token-manager.js";
 import {
   recordToolError,
@@ -19,6 +20,7 @@ import {
 import { getWorkflowRunManager } from "../workflows/run-manager.js";
 import { executeWithTimeout, safeTimeoutMs } from "./execution-timeout.js";
 import { PermissionChecker } from "./permission-checker.js";
+import { getToolOwner } from "./registry.js";
 import { extractAndSanitize } from "./sensitive-output-placeholders.js";
 import { applyEdit } from "./shared/filesystem/edit-engine.js";
 import { sandboxPolicy } from "./shared/filesystem/path-policy.js";
@@ -223,8 +225,19 @@ export class ToolExecutor {
       const toolTimeoutMs = computePerToolTimeoutMs(name, input);
       const execContext = context;
 
+      // Mark the owning plugin as in context (via AsyncLocalStorage) so host
+      // APIs the tool reaches — e.g. resolveCredential — can scope to it. The
+      // context must be established around the `execute()` call itself so the
+      // returned promise carries the binding across its awaits. Non-plugin
+      // tools (default/skill/mcp/workspace) establish no context.
+      const owner = getToolOwner(name);
+      const execPromise =
+        owner?.kind === "plugin"
+          ? runInPluginContext(owner.id, () => tool.execute(input, execContext))
+          : tool.execute(input, execContext);
+
       let execResult: ToolExecutionResult = await executeWithTimeout(
-        tool.execute(input, execContext),
+        execPromise,
         toolTimeoutMs,
         name,
       );