@bevel-software/platform-core-backend 0.13.6 → 0.15.1

package/src/modules/plugins/plugins.routes.ts

@@ -13,6 +13,8 @@ import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { pluginsWorkspaceId } from './plugins.service.js';
 import { PluginProvisionError, type PluginProvisionService } from './plugin-provision.service.js';
+import { PluginLinkError, type PluginLinksService } from './plugin-links.service.js';
+import { PluginRenameError, type PluginRenameService } from './plugin-rename.service.js';
 import type { JoinRequestsService } from './join-requests.service.js';
 import type {
   PluginCatalogEntry,
@@ -61,13 +63,121 @@ export function createPluginsRoutes(
   provision: PluginProvisionService,
   kbDirName: string,
   resolveUser: (req: express.Request) => Promise<AuthUser | null>,
+  /** Optional: a host without the link machinery simply has no link routes. */
+  links?: PluginLinksService,
+  /** Optional: a host without it has no rename route. */
+  rename?: PluginRenameService,
 ): express.Router {
   const router = express.Router();
 
+  /**
+   * Rename a plugin — its identifier, its display name, or both. The
+   * MANAGER's verb (write on the folder's access.md, the gate linking uses).
+   * An identifier change rewrites every grant naming the old identifier in
+   * the same commit; see `PluginRenameService`.
+   *
+   *   PATCH /api/plugins/:name  { name?, displayName? }  → { name, displayName, rewritten }
+   */
+  if (rename) {
+    router.patch('/plugins/:name', async (req, res) => {
+      if (!req.userEmail) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const user = await resolveUser(req);
+      if (!user) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const body = (req.body ?? {}) as { name?: unknown; displayName?: unknown };
+      try {
+        res.json(await rename.rename(user, String(req.params.name), { name: body.name, displayName: body.displayName }));
+      } catch (err) {
+        if (err instanceof PluginRenameError) {
+          res.status(err.status).json({ error: err.message, ...err.payload });
+          return;
+        }
+        if (err instanceof WorkflowDomainError) {
+          res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+          return;
+        }
+        console.error('[plugins] rename failed:', err);
+        res.status(500).json({ error: 'Failed to rename the plugin' });
+      }
+    });
+  }
+
+  /**
+   * Linking shared skills — see `PluginLinksService` for the two-sided write.
+   *
+   *   POST   /api/plugins/:name/links          { skillPath }  → { root, skills }
+   *   DELETE /api/plugins/:name/links?skillPath=              → { root, revoked }
+   *   POST   /api/plugins/:name/links/repair   { skillPath }  → { root }
+   *
+   * Refusals carry a `kind` the UI branches on — `needs-skill-write` (409) is
+   * the one that becomes "request write access".
+   */
+  if (links) {
+    const linkOp = async (
+      req: express.Request,
+      res: express.Response,
+      op: (user: AuthUser, plugin: string, skillPath: string) => Promise<unknown>,
+      skillPathOf: (req: express.Request) => unknown,
+    ) => {
+      if (!req.userEmail) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const user = await resolveUser(req);
+      if (!user) {
+        res.status(401).json({ error: 'Unauthenticated' });
+        return;
+      }
+      const skillPath = skillPathOf(req);
+      if (typeof skillPath !== 'string' || !skillPath.trim()) {
+        res.status(400).json({ error: 'skillPath is required' });
+        return;
+      }
+      try {
+        res.json(await op(user, String(req.params.name), skillPath));
+      } catch (err) {
+        if (err instanceof PluginLinkError) {
+          res.status(err.status).json({ error: err.message, ...err.payload });
+          return;
+        }
+        if (err instanceof WorkflowDomainError) {
+          res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+          return;
+        }
+        console.error('[plugins] link operation failed:', err);
+        res.status(500).json({ error: 'Failed to update the plugin\'s links' });
+      }
+    };
+    const bodyPath = (req: express.Request) => ((req.body ?? {}) as { skillPath?: unknown }).skillPath;
+    router.post('/plugins/:name/links', (req, res) => linkOp(req, res, (u, p, s) => links.link(u, p, s), bodyPath));
+    router.post('/plugins/:name/links/repair', (req, res) =>
+      linkOp(req, res, (u, p, s) => links.repair(u, p, s), bodyPath),
+    );
+    router.delete('/plugins/:name/links', (req, res) =>
+      linkOp(req, res, (u, p, s) => links.unlink(u, p, s), (r) => r.query.skillPath),
+    );
+  }
+
   /** The folder-chain probe for MEMBERSHIP — the folder itself. */
   const memberProbe = (folder: string) => folder;
   /** The FILE probe for discovery/management — the folder's access.md. */
   const accessMdOf = (folder: string) => `${folder}/access.md`;
+  /** A plugin folder's path BELOW the plugins root: `GTM`, or `teams/deep`. */
+  const folderBelowRoot = (folder: string) => folder.slice(folder.indexOf('/') + 1);
+  /**
+   * What a join request is keyed by: the plugin's primary FOLDER path below
+   * the root, not its identity. The request writes into that folder's rules;
+   * a top-level folder keys exactly as every join branch already on a remote
+   * was cut (its name), a nested one by its whole path, so two plugins whose
+   * folders share a basename never share a branch; and a rename of the
+   * identity moves no folder, so it orphans no open request.
+   */
+  const joinKeyOf = (g: PluginCatalogEntry) => folderBelowRoot(g.folders[0]);
 
   const probesFor = (plugins: PluginCatalogEntry[]): string[] => [
     ...new Set(plugins.flatMap((g) => g.folders.flatMap((f) => [memberProbe(f), accessMdOf(f)]))),
@@ -122,15 +232,18 @@ export function createPluginsRoutes(
         const owner = any(owned, g, memberProbe);
         const discoverable = member || any(readable, g, accessMdOf);
         if (!member && !manager && !discoverable) continue; // absent — fail closed
-        const joinCr = member ? null : openJoinCr(mine, email, g.name);
+        const joinCr = member ? null : openJoinCr(mine, email, joinKeyOf(g));
         plugins.push({
           name: g.name,
+          displayName: g.displayName,
           folders: g.folders,
           canRead: member,
           canWrite: manager,
           isOwner: owner,
+          linksAreManaged: g.linksAreManaged,
           skillCount: g.skillCount,
           toolCount: g.toolCount,
+          brokenLinks: g.brokenLinks,
           owners: g.owners,
           writers: g.writers,
           readers: g.readers,
@@ -230,7 +343,7 @@ export function createPluginsRoutes(
         res.status(401).json({ error: 'Unauthenticated' });
         return;
       }
-      // Case-sensitive, like `pluginOfPath` — the plugin name IS the folder name.
+      // By identity — the manifest name the catalog keys on.
       const plugin = (await pluginIndex.catalog()).find((g) => g.name === req.params.name);
       const wsId = pluginsWorkspaceId();
       const ownerVerdicts = plugin
@@ -242,7 +355,10 @@ export function createPluginsRoutes(
         res.status(404).json({ error: 'Unknown plugin', kind: 'unknown-plugin' });
         return;
       }
-      await provision.deletePlugin(user, plugin.name);
+      // Provisioning works on FOLDERS (it created one); the identity only
+      // found the plugin. The whole path below the root, so a nested plugin
+      // is deleted where it is.
+      await provision.deletePlugin(user, folderBelowRoot(plugin.folders[0]));
       pluginIndex.invalidate();
       res.json({ ok: true });
     } catch (err) {
@@ -268,7 +384,7 @@ export function createPluginsRoutes(
         return;
       }
       const catalog = await pluginIndex.catalog();
-      // Case-sensitive, like `pluginOfPath` — the plugin name IS the folder name.
+      // By identity — the manifest name the catalog keys on.
       const plugin = catalog.find((g) => g.name === req.params.name);
       const wsId = pluginsWorkspaceId();
       // Same ANY-folder shape `GET /plugins` resolves with, so a plugin can
@@ -298,8 +414,8 @@ export function createPluginsRoutes(
       // expects.
       const folder = plugin.folders[0];
 
-      const branch = joinBranchFor(email, plugin.name);
-      const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, plugin.name);
+      const branch = joinBranchFor(email, joinKeyOf(plugin));
+      const existing = openJoinCr(await workflow.listChangeRequestsAuthoredBy(email), email, joinKeyOf(plugin));
       if (existing) {
         res.json({ ok: true, number: existing.number });
         return;
@@ -323,14 +439,15 @@ export function createPluginsRoutes(
       );
       if (spliced.changed) {
         await workspaceService.writeFile(ws.id, accessPath, spliced.text);
-        await workflow.commitChanges(ws.id, user, `Request access to ${plugin.name}`);
+        await workflow.commitChanges(ws.id, user, `Request access to ${plugin.displayName}`);
       }
       const detail = await workflow.openChangeRequest(ws.id, user, {
         sourceBranch: branch,
         targetBranch: DEFAULT_BRANCH,
-        title: `Join request: ${plugin.name}`,
+        // People read these: the display name, not the identifier.
+        title: `Join request: ${plugin.displayName}`,
         description:
-          `${user.name} asked to join ${plugin.name}. A manager of the plugin accepts by ` +
+          `${user.name} asked to join ${plugin.displayName}. A manager of the plugin accepts by ` +
           `granting the access this branch proposes; the request closes itself once ` +
           `every proposal has landed.`,
       });
@@ -392,7 +509,7 @@ export function createPluginsRoutes(
       if (!ctx) return;
       const crs = await workflow.listChangeRequests();
       res.json({
-        requests: await joinRequests.list(ctx.plugin.name, ctx.folder, crs, ctx.user),
+        requests: await joinRequests.list(joinKeyOf(ctx.plugin), ctx.folder, crs, ctx.user),
       });
     } catch (err) {
       console.error('[plugins] failed to list join requests:', err);
@@ -422,7 +539,7 @@ export function createPluginsRoutes(
         res.status(404).json({ error: 'Not found' });
         return;
       }
-      res.json({ closed: await joinRequests.reconcile(ctx.plugin.name, ctx.folder, cr, ctx.user) });
+      res.json({ closed: await joinRequests.reconcile(joinKeyOf(ctx.plugin), ctx.folder, cr, ctx.user) });
     } catch (err) {
       console.error('[plugins] failed to reconcile a join request:', err);
       res.status(500).json({ error: 'Failed to update the request' });

package/src/modules/plugins/plugins.service.ts

@@ -1,11 +1,6 @@
 import path from 'node:path';
-import fs from 'node:fs/promises';
-import type { Dirent } from 'node:fs';
 import {
   DEFAULT_BRANCH,
-  PLUGINS_DIR,
-  pluginOfPath,
-  isPersonalPluginFolder,
 } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
@@ -14,6 +9,9 @@ import type { ISkillService } from '../skills/skills.contract.js';
 import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
 import type { PluginCatalogEntry, IPluginIndexService } from './plugins.contract.js';
+import type { PluginLinkIndex } from './plugin-links.js';
+import type { PluginSource } from './discovery/plugin-source.js';
+import { KbPluginSource } from './discovery/kb-plugin-source.js';
 
 const CACHE_TTL_MS = 60_000;
 
@@ -52,6 +50,14 @@ export class PluginIndexService implements IPluginIndexService {
     private readonly toolManualService: IToolManualService,
     private readonly kbDirName: string,
     now: () => number = Date.now,
+    /**
+     * The link index, when the deployment has one: a plugin's skill count is
+     * then inline PLUS linked. Optional so hosts composing their own service
+     * set (and older tests) keep the inline-only count.
+     */
+    private readonly links?: PluginLinkIndex,
+    /** Where plugins come from — native manifests unless a dialect is configured. */
+    private readonly source: PluginSource = new KbPluginSource(),
   ) {
     this.cache = new TtlCache(CACHE_TTL_MS, now);
   }
@@ -63,6 +69,9 @@ export class PluginIndexService implements IPluginIndexService {
   async catalog(): Promise<PluginCatalogEntry[]> {
     const cached = this.cache.get();
     if (cached) return cached;
+    // See `TtlCache.begin`: taken before the read so an `invalidate()` that
+    // lands mid-build discards this result instead of being overwritten by it.
+    const token = this.cache.begin();
     const entries = await this.build();
     // A failed scan and a KB with genuinely no plugin folders both serve `[]`,
     // but only the second is a fact worth holding for the TTL. Caching the
@@ -72,7 +81,7 @@ export class PluginIndexService implements IPluginIndexService {
     // never arrive in that window. So a degraded read is served, not stored,
     // and the next caller retries.
     if (entries === null) return [];
-    this.cache.set(entries);
+    this.cache.set(entries, token);
     return entries;
   }
 
@@ -94,12 +103,13 @@ export class PluginIndexService implements IPluginIndexService {
       const wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
       const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
-      const folders = await this.scanFolders(kbRoot);
-      if (folders.size === 0) return [];
+      const scanned = await this.scanFolders(kbRoot);
+      if (scanned.size === 0) return [];
+      const folders = new Map([...scanned].map(([name, p]) => [name, p.folders]));
 
-      const [skillCounts, toolCounts] = await Promise.all([
-        this.countSkills(),
-        this.countTools(),
+      const [{ skillCounts, brokenLinkCounts }, toolCounts] = await Promise.all([
+        this.countThroughLinks(folders),
+        this.countTools(folders),
       ]);
 
       const entries: PluginCatalogEntry[] = [];
@@ -113,9 +123,12 @@ export class PluginIndexService implements IPluginIndexService {
         ]);
         entries.push({
           name,
+          displayName: scanned.get(name)?.displayName ?? name,
           folders: pluginFolders,
+          linksAreManaged: scanned.get(name)?.linksAreManaged ?? false,
           skillCount: skillCounts.get(name) ?? 0,
           toolCount: toolCounts.get(name) ?? 0,
+          brokenLinks: brokenLinkCounts.get(name) ?? 0,
           owners,
           writers,
           readers,
@@ -130,59 +143,99 @@ export class PluginIndexService implements IPluginIndexService {
     }
   }
 
-  /** name → repo-relative plugin folder (always a single-element list). */
-  private async scanFolders(kbRoot: string): Promise<Map<string, string[]>> {
-    const byName = new Map<string, string[]>();
-    let children: Dirent[];
-    try {
-      children = await fs.readdir(path.join(kbRoot, PLUGINS_DIR), { withFileTypes: true });
-    } catch {
-      return byName; // a KB without a `Plugins/` root simply has no plugins
+  /**
+   * name → repo-relative plugin folder (always a single-element list), from
+   * the configured source. Personal folders live under Plugins/ but are not
+   * plugins: one exists per person, private by construction, and listing them
+   * would put a locked row per employee in everyone's index. `exists` is the
+   * source's existence rule (see `DiscoveredPlugin`) — for native plugins,
+   * the `access.md` the class doc describes.
+   */
+  private async scanFolders(
+    kbRoot: string,
+  ): Promise<Map<string, { folders: string[]; linksAreManaged: boolean; displayName: string }>> {
+    const byName = new Map<string, { folders: string[]; linksAreManaged: boolean; displayName: string }>();
+    const discovered = await this.source.discover(kbRoot);
+    for (const w of discovered.warnings) console.warn(`[plugins] ${w}`);
+    for (const plugin of discovered.plugins) {
+      if (plugin.personal || !plugin.exists) continue;
+      byName.set(plugin.name, {
+        folders: [plugin.folder],
+        linksAreManaged: plugin.linksAreManaged,
+        displayName: plugin.displayName,
+      });
     }
-    const candidates = children.filter(
-      (child) =>
-        child.isDirectory() &&
-        !child.name.startsWith('.') &&
-        // Personal folders live under Plugins/ but are not plugins: one exists
-        // per person, private by construction, and listing them would put a
-        // locked row per employee in everyone's index.
-        !isPersonalPluginFolder(child.name),
-    );
-    // A plugin exists exactly when its folder carries an `access.md` (see the
-    // class doc) — stat that file, don't trust the directory.
-    const verdicts = await Promise.all(
-      candidates.map(async (child) => {
-        try {
-          return (await fs.stat(path.join(kbRoot, PLUGINS_DIR, child.name, 'access.md'))).isFile();
-        } catch {
-          return false;
-        }
-      }),
-    );
-    candidates.forEach((child, i) => {
-      if (verdicts[i]) byName.set(child.name, [`${PLUGINS_DIR}/${child.name}`]);
-    });
     return byName;
   }
 
-  private async countSkills(): Promise<Map<string, number>> {
-    // `undefined` is the documented GLOBAL, unfiltered mode — counts are a
-    // property of the plugin, not of who is asking.
-    return bucketByPlugin(await this.skillService.listSkills(undefined));
+  /**
+   * Two counts from ONE read of the link index — the membership is built
+   * once per cold catalog, not once per count: `TtlCache` has no
+   * single-flight, so two concurrent readers of an empty cache would each
+   * discover the tree and resolve every linked skill's access.
+   *
+   *  - `skillCounts`: with links, a skill counts for EVERY plugin that holds
+   *    it — inline in its folder, or linked from a manifest. Personal folders
+   *    are already absent from the membership (they are places, not plugins).
+   *  - `brokenLinkCounts`: how many linked skills each plugin's members
+   *    cannot read — memberships reported as linked but not granted. From the
+   *    UNFILTERED index, so the count reaches the plugin's managers even when
+   *    the missing grant locks them out of the skill too.
+   *
+   * Without a link index: skills bucket by folder, and no link can be broken.
+   */
+  private async countThroughLinks(
+    folders: Map<string, string[]>,
+  ): Promise<{ skillCounts: Map<string, number>; brokenLinkCounts: Map<string, number> }> {
+    const skillCounts = new Map<string, number>();
+    const brokenLinkCounts = new Map<string, number>();
+    if (!this.links) {
+      // `undefined` is the documented GLOBAL, unfiltered mode — counts are a
+      // property of the plugin, not of who is asking.
+      return {
+        skillCounts: bucketByFolder(await this.skillService.listSkills(undefined), folders),
+        brokenLinkCounts,
+      };
+    }
+    for (const memberships of (await this.links.membership()).bySkill.values()) {
+      for (const m of memberships) {
+        skillCounts.set(m.name, (skillCounts.get(m.name) ?? 0) + 1);
+        if (m.linked && !m.granted) brokenLinkCounts.set(m.name, (brokenLinkCounts.get(m.name) ?? 0) + 1);
+      }
+    }
+    return { skillCounts, brokenLinkCounts };
   }
 
-  private async countTools(): Promise<Map<string, number>> {
-    return bucketByPlugin(await this.toolManualService.listAllSummaries());
+  /**
+   * Tools belong to the plugin whose FOLDER holds them — matched by path
+   * prefix against the discovered folders, not by `pluginOfPath`'s
+   * second-segment rule, so a dialect plugin nested three folders deep still
+   * counts the servers its bundle expands.
+   */
+  private async countTools(folders: Map<string, string[]>): Promise<Map<string, number>> {
+    const counts = new Map<string, number>();
+    const byFolder = [...folders.entries()].map(([name, [folder]]) => ({ name, prefix: `${folder}/` }));
+    for (const tool of await this.toolManualService.listAllSummaries()) {
+      const owner = byFolder.find((f) => tool.path.startsWith(f.prefix));
+      if (!owner) continue;
+      counts.set(owner.name, (counts.get(owner.name) ?? 0) + 1);
+    }
+    return counts;
   }
 }
 
-/** Count items per plugin folder name; ungrouped items (`null`) count nowhere. */
-function bucketByPlugin(items: { path: string }[]): Map<string, number> {
+/**
+ * Count items per plugin by FOLDER PREFIX against the discovered folders —
+ * not by `pluginOfPath`'s second-segment rule, which would file a nested
+ * plugin's skills under its grouping folder. Items in no plugin count nowhere.
+ */
+function bucketByFolder(items: { path: string }[], folders: Map<string, string[]>): Map<string, number> {
   const counts = new Map<string, number>();
+  const byFolder = [...folders.entries()].map(([name, [folder]]) => ({ name, prefix: `${folder}/` }));
   for (const item of items) {
-    const plugin = pluginOfPath(item.path);
-    if (plugin === null) continue;
-    counts.set(plugin, (counts.get(plugin) ?? 0) + 1);
+    const owner = byFolder.find((f) => item.path.startsWith(f.prefix));
+    if (!owner) continue;
+    counts.set(owner.name, (counts.get(owner.name) ?? 0) + 1);
   }
   return counts;
 }

package/src/modules/secrets-vault/__tests__/connect-pending.route.test.ts

@@ -76,6 +76,10 @@ async function baseUrlWith(auth: { userId?: string; email?: string }): Promise<s
       secretsVault,
       toolManualService,
       accessControl,
+      // These tests are about the credential write, not the probe.
+      connectionProbe: {
+        probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+      },
       stateSecret: 'test-secret',
       publicBackendUrl: 'http://localhost:3000',
       publicFrontendUrl: 'http://localhost:5173',
@@ -174,6 +178,10 @@ describe('GET /api/connect/pending — OAuth scope coverage', () => {
         secretsVault: vaultWithGranted(grantedScopes),
         toolManualService: oauthTool,
         accessControl,
+        // These tests are about the credential write, not the probe.
+        connectionProbe: {
+          probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+        },
         stateSecret: 'test-secret',
         publicBackendUrl: 'http://localhost:3000',
         publicFrontendUrl: 'http://localhost:5173',
@@ -257,6 +265,10 @@ describe('GET /api/connect/pending — tool sign-ins are not double-listed as st
         secretsVault: vault,
         toolManualService: oauthTool,
         accessControl,
+        // These tests are about the credential write, not the probe.
+        connectionProbe: {
+          probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+        },
         stateSecret: 'test-secret',
         publicBackendUrl: 'http://localhost:3000',
         publicFrontendUrl: 'http://localhost:5173',

package/src/modules/secrets-vault/__tests__/oauth-return-to.route.test.ts

@@ -31,8 +31,7 @@ const TOOL_PATH = 'Tools/weather.tool';
 const USER = 'user@x.com';
 const RETURN_TO = '/skills-and-tools/tools/weather';
 
-const toolManualService = {
-  listAccessible: async () => [
+const MANUALS = [
     {
       slug: 'weather',
       name: 'weather',
@@ -51,7 +50,10 @@ const toolManualService = {
         },
       ],
     },
-  ],
+];
+
+const toolManualService = {
+  listAccessible: async () => MANUALS,
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
 
 const accessControl = {
@@ -65,10 +67,15 @@ const secretsVault = {
   completeOAuth,
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
 
+const connectionProbe = {
+  probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['connectionProbe'];
+
 const deps = {
   secretsVault,
   toolManualService,
   accessControl,
+  connectionProbe,
   stateSecret: STATE_SECRET,
   publicBackendUrl: 'http://localhost:3000',
   publicFrontendUrl: FRONTEND,

package/src/modules/secrets-vault/__tests__/tool-owner-gate.route.test.ts

@@ -28,6 +28,9 @@ const toolManualService = {
       setup: { kind: 'oauth-manual' as const, reason: 'no authorization-server metadata at https://weather.example' },
       variables: [
         { name: 'SHARED_KEY', scope: 'admin' as const, label: 'Org key' },
+        // A plain per-user key, so the user-scoped write path (and the
+        // per-user invalidation it owes) is exercised alongside the shared one.
+        { name: 'MY_KEY', scope: 'user' as const, label: 'Your key' },
         {
           name: 'SIGNIN',
           scope: 'user' as const,
@@ -56,9 +59,11 @@ const toolManualService = {
   ],
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
 
+const putStatic = vi.fn(async () => ({ id: 'u1' }));
 const putSharedStatic = vi.fn(async () => ({ id: 's1' }));
 const putSharedOAuthClientSecret = vi.fn(async () => {});
 const secretsVault = {
+  putStatic,
   putSharedStatic,
   putSharedOAuthClientSecret,
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
@@ -69,6 +74,10 @@ const accessControl = {
   canWrite: async (_ws: string, email: string, path: string) => email === WRITER && path === TOOL_PATH,
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['accessControl'];
 
+const connectionProbe = {
+  probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['connectionProbe'];
+
 let httpServer: HttpServer | undefined;
 
 async function baseUrlAs(email: string): Promise<string> {
@@ -85,6 +94,7 @@ async function baseUrlAs(email: string): Promise<string> {
       secretsVault,
       toolManualService,
       accessControl,
+      connectionProbe,
       stateSecret: 'test-secret',
       publicBackendUrl: 'http://localhost:3000',
       publicFrontendUrl: 'http://localhost:5173',
@@ -102,6 +112,7 @@ afterEach(async () => {
   httpServer = undefined;
   putSharedStatic.mockClear();
   putSharedOAuthClientSecret.mockClear();
+  putStatic.mockClear();
 });
 
 describe('tool owner gate — shared config requires WRITE on the `.tool` file', () => {
@@ -116,6 +127,21 @@ describe('tool owner gate — shared config requires WRITE on the `.tool` file',
     expect(putSharedStatic).toHaveBeenCalledWith(expect.objectContaining({ key: 'weather_SHARED_KEY' }));
   });
 
+  it('a mere READER may still set their OWN value for the same tool', async () => {
+    // The gate is on the SHARED value only. One person's own key says nothing
+    // about anyone else's, so needing write access to the `.tool` file to type
+    // your own credential would lock every reader out of the tools they can see.
+    const base = await baseUrlAs(READER);
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/MY_KEY/user`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'mine-123' }),
+    });
+    expect(res.status).toBe(201);
+    expect(putStatic).toHaveBeenCalledWith(expect.objectContaining({ key: 'weather_MY_KEY' }));
+    expect(putSharedStatic).not.toHaveBeenCalled();
+  });
+
   it('a non-writer is refused (403), even though they can READ the tool', async () => {
     const base = await baseUrlAs(READER);
     const res = await fetch(`${base}/api/secrets/tools/weather/vars/SHARED_KEY/admin`, {

package/src/modules/secrets-vault/db-secrets-vault.service.ts

@@ -97,7 +97,7 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     if (!this.cryptoInstance) {
       if (!this.encKey) {
         throw new InvalidSecretError(
-          'Secrets require an encryption key — set CONNECTOR_CONFIG_ENC_KEY (or SHAREPOINT_TOKEN_ENC_KEY).',
+          'Secrets require an encryption key — set SECRETS_ENC_KEY.',
         );
       }
       this.cryptoInstance = new TokenCrypto(this.encKey);