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

package/src/modules/skills/skills.contract.ts

@@ -7,13 +7,45 @@
  * bundled file's content (level 3).
  */
 
+/**
+ * One plugin a skill belongs to — by sitting INSIDE the plugin folder
+ * (`linked: false`) or by being LINKED from the plugin's manifest
+ * (`linked: true`). For a link, `granted` is the link's HEALTH: whether the
+ * plugin's members can read the skill through it. For a link this platform
+ * manages that is whether the skill's own access rules name the plugin's
+ * `plugin/<Name>/read` principal — the link service writes that grant with
+ * the link, so `false` means a hand edit took it away. A link read from an
+ * external plugin format needs no grant (the skill's own scope decides who
+ * reads it) and is always `true`; the flag never proves a principal exists.
+ */
+export interface PluginMembership {
+  /** The plugin folder name. */
+  name: string;
+  linked: boolean;
+  granted: boolean;
+}
+
 export interface SkillSummary {
   /** Canonical id = the skill's folder name (e.g. `rfi`). */
   name: string;
   description: string;
   version?: string;
+  /** The governance owner from `metadata.owner`, when the skill declares one. */
+  owner?: string;
+  /**
+   * The governance lifecycle from `metadata.lifecycle`, lowercased — `active`
+   * (or absent), `deprecated` (still served, flagged), `retired` (served to the
+   * catalog for its owners, never compiled into a distribution).
+   */
+  lifecycle?: string;
   /** Repo-root-relative skill folder, e.g. `Plugins/Everyone/rfi`. */
   path: string;
+  /**
+   * The plugins this skill belongs to, decorated onto the catalog by the
+   * browser route (the catalog itself is plugin-unaware). Absent on the agent
+   * surfaces, which load skills by name and never by plugin.
+   */
+  plugins?: PluginMembership[];
 }
 
 export interface Skill extends SkillSummary {

package/src/modules/skills/skills.routes.ts

@@ -1,6 +1,21 @@
 import express from 'express';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import type { IPendingSkillService, ISkillService } from './skills.contract.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { IPendingSkillService, ISkillService, PluginMembership } from './skills.contract.js';
+
+/** The slice of the plugin link index this surface reads — see `PluginLinkIndex`. */
+export interface SkillMembershipSource {
+  membership(): Promise<{
+    bySkill: Map<string, PluginMembership[]>;
+    byPlugin: Map<string, { folder: string }>;
+  }>;
+}
+
+/** The one access verdict this surface needs: may the caller read a path on the default branch? */
+export interface SkillMembershipGate {
+  canReadBatch(workspaceId: string, userEmail: string, paths: string[]): Promise<Map<string, boolean>>;
+}
 
 /**
  * Browser-facing (JWT) skill routes for the `/`-command menu, mounted behind
@@ -8,14 +23,27 @@ import type { IPendingSkillService, ISkillService } from './skills.contract.js';
  * so discovery, default-branch pinning, and per-user `canRead` filtering live
  * ONCE — the frontend never re-implements skill discovery or bypasses access.
  *
- *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user)
+ *   GET /api/skills            → { skills: SkillSummary[] }   (filtered to this user,
+ *                                                              each with its `plugins`)
  *   GET /api/skills/pending    → { skills: PendingSkill[] }   (proposed, not released)
  *   GET /api/skills/:name      → GetSkillResult               (body + files)
  *   GET /api/skills/:name?file=… → GetSkillResult             (a bundled file's content)
+ *
+ * `plugins` is decorated HERE, not in the catalog: the catalog is what agents
+ * load by name and it stays plugin-unaware; the browser is the surface that
+ * groups skills by plugin. Optional dependency, so a host without the link
+ * index gets undecorated summaries rather than a 500.
  */
 export function createSkillsRoutes(
   skillService: ISkillService,
   pendingSkills?: IPendingSkillService,
+  links?: SkillMembershipSource,
+  /**
+   * With `links`: the memberships a caller sees name only plugins they may
+   * DISCOVER (read the plugin's access.md — the plugin index's own listing
+   * verdict), so this surface never reveals a plugin `/api/plugins` omits.
+   */
+  gate?: SkillMembershipGate,
 ): express.Router {
   const router = express.Router();
 
@@ -25,7 +53,35 @@ export function createSkillsRoutes(
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
-    res.json({ skills: await skillService.listSkills(email) });
+    const skills = await skillService.listSkills(email);
+    if (!links) {
+      res.json({ skills });
+      return;
+    }
+    let bySkill: Map<string, PluginMembership[]>;
+    // Fail closed: memberships without a gate to judge them by name nothing.
+    let discoverable: (plugin: string) => boolean = () => false;
+    try {
+      const membership = await links.membership();
+      bySkill = membership.bySkill;
+      if (gate) {
+        const folders = [...membership.byPlugin.entries()];
+        const verdicts = folders.length
+          ? await gate.canReadBatch(
+              workspaceIdForBranch(DEFAULT_BRANCH),
+              email,
+              folders.map(([, p]) => `${p.folder}/access.md`),
+            )
+          : new Map<string, boolean>();
+        const visible = new Set(folders.filter(([, p]) => verdicts.get(`${p.folder}/access.md`) === true).map(([name]) => name));
+        discoverable = (plugin) => visible.has(plugin);
+      }
+    } catch {
+      bySkill = new Map(); // membership is a decoration; the shelf must not fall with it
+    }
+    res.json({
+      skills: skills.map((s) => ({ ...s, plugins: (bySkill.get(s.path) ?? []).filter((m) => discoverable(m.name)) })),
+    });
   });
 
   /**

package/src/modules/skills/skills.service.ts

@@ -1,13 +1,14 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import { parseDocument } from 'yaml';
-import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { extractFrontmatter, resolveDeclaredId, dedupeById } from '../../shared/frontmatter-id.js';
 import { walkFiles } from '../../shared/fs-walk.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
+import { BevelIgnoreStack } from '../workspace/bevel-ignore.js';
 import type {
   ISkillService,
   GetSkillResult,
@@ -75,6 +76,9 @@ export class SkillService implements ISkillService {
     if (file !== undefined) {
       if (!isSafeRelFile(file)) return { ok: false, error: 'invalid_file' };
       const repoPath = `${found.summary.path}/${file}`;
+      // Only a file the catalog LISTS is served: the listing already applied
+      // the ignore rules, so a path that is not in it is one they hid.
+      if (!found.files.includes(repoPath)) return { ok: false, error: 'not_found' };
       try {
         const content = await this.workspaceService.readFile(wsId, `${this.kbDirName}/${repoPath}`);
         return { ok: true, kind: 'file', file: { name, file, path: repoPath, content } };
@@ -97,15 +101,20 @@ export class SkillService implements ISkillService {
   private async scan(): Promise<ParsedSkill[]> {
     const cached = this.cache.get();
     if (cached) return cached;
+    // Token first: a merge's `invalidate()` can land while `scanDisk` is still
+    // reading the pre-merge tree, and storing that read afterwards would undo
+    // the drop for a full TTL.
+    const token = this.cache.begin();
     const skills = await this.scanDisk();
-    this.cache.set(skills);
+    this.cache.set(skills, token);
     return skills;
   }
 
   private async scanDisk(): Promise<ParsedSkill[]> {
-    // Ensure the default-branch clone exists, then scan its Plugins/ dir. Any
-    // failure (no workspace, no Plugins/ dir) degrades to an empty catalog — the
-    // manual/tools must never break because skills can't be read.
+    // Ensure the default-branch clone exists, then scan its Skills/ and
+    // Plugins/ roots. Any failure (no workspace, no such dir) degrades to an
+    // empty catalog — the manual/tools must never break because skills can't
+    // be read.
     let wsId: string;
     try {
       wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
@@ -115,20 +124,34 @@ export class SkillService implements ISkillService {
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
     // Skills may be grouped in category subfolders (each carrying its own
-    // access.md), so a SKILL.md can live at any depth under the root. Walk the
-    // tree and treat every folder that directly contains a SKILL.md as a skill;
-    // don't descend past it — its inner files are bundled assets, not nested
-    // skills. The skill name is the leaf folder name; its path is the full
-    // repo-relative folder (e.g. `Plugins/Development/coding-guidelines`).
+    // access.md), so a SKILL.md can live at any depth under either root. Walk
+    // the tree and treat every folder that directly contains a SKILL.md as a
+    // skill; don't descend past it — its inner files are bundled assets, not
+    // nested skills. The skill name is the leaf folder name; its path is the
+    // full repo-relative folder (e.g. `Skills/Engineering/deploy`).
+    //
+    // `.bevelignore` files INSIDE a root are honoured on the way down, the
+    // same layered rules the file tree applies: a repository that carries a
+    // build output beside its source (a `dist/` holding compiled copies of
+    // every skill) would otherwise list each skill twice and refuse the
+    // duplicate — the wrong one, half the time. The REPO-ROOT file is
+    // deliberately not consulted: it is where the template hides `Plugins/`
+    // from the Knowledge tree, and a rule that hides a root from the browser
+    // must not empty the catalog that root exists to feed.
     const out: ParsedSkill[] = [];
-    const walk = async (dir: string, relFolder: string): Promise<void> => {
+    const walk = async (dir: string, relFolder: string, ignore: BevelIgnoreStack): Promise<void> => {
       let entries: import('node:fs').Dirent[];
       try {
         entries = await fs.readdir(dir, { withFileTypes: true });
       } catch {
         return;
       }
+      ignore = await ignore.extendedWith(dir);
       if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) {
+        // A skill folder is a LEAF whatever the ignore rules say of it: a rule
+        // naming its SKILL.md suppresses the skill, it does not turn the
+        // folder's assets into skills of their own.
+        if (ignore.isIgnored(path.join(dir, 'SKILL.md'), false)) return;
         let raw: string;
         try {
           raw = await fs.readFile(path.join(dir, 'SKILL.md'), 'utf-8');
@@ -144,26 +167,43 @@ export class SkillService implements ISkillService {
         const declared = resolveDeclaredId(fm.frontmatter, path.basename(dir));
         const name = isSafeSkillName(declared) ? declared : path.basename(dir);
         out.push({
-          summary: { name, description: fm.description, version: fm.version, path: relFolder },
+          summary: {
+            name,
+            description: fm.description,
+            version: fm.version,
+            owner: fm.owner,
+            lifecycle: fm.lifecycle,
+            path: relFolder,
+          },
           body: fm.body,
           allowedTools: fm.allowedTools,
-          files: await listBundledFiles(dir, relFolder),
+          files: await listBundledFiles(dir, relFolder, ignore),
         });
         return; // a skill folder is a leaf — its subfolders hold assets, not skills
       }
       for (const entry of entries) {
         if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
-        await walk(path.join(dir, entry.name), `${relFolder}/${entry.name}`);
+        const abs = path.join(dir, entry.name);
+        if (ignore.isIgnored(abs, true)) continue;
+        await walk(abs, `${relFolder}/${entry.name}`, ignore);
       }
     };
-    await walk(path.join(kbRoot, PLUGINS_DIR), PLUGINS_DIR);
+    // Each root starts its own ignore stack (the walk extends it with the
+    // root's own file first). Order is cosmetic: the sort below is by name
+    // then path, so a same-named pair resolves the same way regardless.
+    await walk(path.join(kbRoot, SKILLS_DIR), SKILLS_DIR, BevelIgnoreStack.empty());
+    await walk(path.join(kbRoot, PLUGINS_DIR), PLUGINS_DIR, BevelIgnoreStack.empty());
     // A skill's id (frontmatter `id`/`name`, else folder name) is how getSkill()
-    // resolves it, so it must be unique. Sort by (name, path) for a deterministic
-    // winner, then REFUSE later duplicates via the shared dedup — the same rule
-    // tools use (no silent auto-suffix that would rebind an id under the caller).
+    // resolves it, so it must be unique. Sort by (name, root, path) for a
+    // deterministic winner — the shared root FIRST, since `Skills/` is a
+    // skill's canonical home and a same-named inline copy is the stale one —
+    // then REFUSE later duplicates via the shared dedup — the same rule tools
+    // use (no silent auto-suffix that would rebind an id under the caller).
+    const rootRank = (p: string) => (p === SKILLS_DIR || p.startsWith(`${SKILLS_DIR}/`) ? 0 : 1);
     out.sort(
       (a, b) =>
         a.summary.name.localeCompare(b.summary.name) ||
+        rootRank(a.summary.path) - rootRank(b.summary.path) ||
         a.summary.path.localeCompare(b.summary.path),
     );
     return dedupeById(out, (s) => s.summary.name, (s, id) =>
@@ -209,6 +249,10 @@ function scalarToString(value: unknown): string | undefined {
 export function parseSkillFrontmatter(raw: string): {
   description: string;
   version?: string;
+  /** `metadata.owner` (or a top-level `owner`) — the governance record's owner, verbatim. */
+  owner?: string;
+  /** `metadata.lifecycle` (or top-level) — e.g. `active`, `deprecated`, `retired`; lowercased. */
+  lifecycle?: string;
   allowedTools?: string[];
   body: string;
   /** The parsed frontmatter object (for shared id resolution: `id`/`name`). */
@@ -233,6 +277,11 @@ export function parseSkillFrontmatter(raw: string): {
   const description = typeof data.description === 'string' ? data.description.trim() : '';
   const metadata = (data.metadata ?? {}) as Record<string, unknown>;
   const version = scalarToString(data.version) ?? scalarToString(metadata.version);
+  // The governance record: `metadata.owner` / `metadata.lifecycle` first (the
+  // agentskills convention this catalog reads), a top-level spelling second.
+  const owner = (scalarToString(metadata.owner) ?? scalarToString(data.owner))?.trim() || undefined;
+  const lifecycle =
+    (scalarToString(metadata.lifecycle) ?? scalarToString(data.lifecycle))?.trim().toLowerCase() || undefined;
 
   // `allowed-tools` is a space-separated string (agentskills) or a YAML list.
   const at = data['allowed-tools'];
@@ -242,12 +291,25 @@ export function parseSkillFrontmatter(raw: string): {
       ? at.split(/\s+/).filter(Boolean)
       : undefined;
 
-  return { description, version, allowedTools, body, frontmatter: data };
+  return { description, version, owner, lifecycle, allowedTools, body, frontmatter: data };
 }
 
-/** Repo-root-relative paths of every bundled file under a skill folder (excludes SKILL.md). */
-async function listBundledFiles(dir: string, relFolder: string): Promise<string[]> {
+/**
+ * Repo-root-relative paths of every bundled file under a skill folder
+ * (excludes SKILL.md), under the same ignore rules the walk applied on the
+ * way down — a rule in the skill's own `.bevelignore` or any folder above
+ * hides an asset from the listing, and therefore (see `getSkill`) from
+ * being served.
+ */
+async function listBundledFiles(dir: string, relFolder: string, ignore: BevelIgnoreStack): Promise<string[]> {
+  const hidden = (rel: string): boolean => {
+    const parts = rel.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      if (ignore.isIgnored(path.join(dir, ...parts.slice(0, i)), true)) return true;
+    }
+    return ignore.isIgnored(path.join(dir, ...parts), false);
+  };
   return (await walkFiles(dir, () => true))
-    .filter((rel) => rel !== 'SKILL.md')
+    .filter((rel) => rel !== 'SKILL.md' && !hidden(rel))
     .map((rel) => `${relFolder}/${rel}`);
 }

package/src/modules/tool-auth/external-api-key.interface.ts

@@ -22,6 +22,12 @@ declare global {
 export interface ExternalApiKeySummary {
   id: string;
   label: string;
+  /**
+   * What the key was minted AS — `key` for one a person created by hand,
+   * another kind for one a flow minted on their behalf (a Claude link).
+   * Stored with the row; the label is the person's to edit and proves nothing.
+   */
+  kind: string;
   createdAt: number;
   lastUsedAt: number | null;
   revokedAt: number | null;
@@ -37,6 +43,19 @@ export interface MintedExternalApiKey {
   summary: ExternalApiKeySummary;
 }
 
+/** The kind of a key a person creates by hand. */
+export const DEFAULT_KEY_KIND = 'key';
+
+/**
+ * How a key is minted. `kind` names one of the kinds the service was built
+ * with, each of which carries its own plaintext prefix (the tenant's for the
+ * default kind, `gho_` for a Claude link); an unknown kind is refused, since
+ * nothing would route its bearer back.
+ */
+export interface MintOptions {
+  kind?: string;
+}
+
 /**
  * Contract for connection-key (API token) lifecycle. Used by the MCP auth
  * middleware to resolve a Bearer token to a Bevel user, and by the settings
@@ -59,7 +78,7 @@ export interface IExternalApiKeyService {
    * plaintext is **only** returned here — there is no read path that can
    * surface it again.
    */
-  mint(userId: string, label: string): Promise<MintedExternalApiKey>;
+  mint(userId: string, label: string, options?: MintOptions): Promise<MintedExternalApiKey>;
 
   /**
    * Resolve a plaintext token to the owning user. Returns null when the

package/src/modules/tool-auth/external-api-key.service.ts

@@ -8,36 +8,53 @@ import {
   TokenNotFoundError,
   TokenStillActiveError,
 } from './external-api-key.errors.js';
-import type {
-  ExternalApiKeySummary,
-  IExternalApiKeyService,
-  MintedExternalApiKey,
+import {
+  DEFAULT_KEY_KIND,
+  type ExternalApiKeySummary,
+  type IExternalApiKeyService,
+  type MintOptions,
+  type MintedExternalApiKey,
 } from './external-api-key.interface.js';
 
-// Plaintext format: `<tenant>_<43 base64url chars>`. 32 random bytes encoded
+// Plaintext format: `<prefix><43 base64url chars>`. 32 random bytes encoded
 // base64url is 43 chars and gives 256 bits of entropy — overkill against
-// brute force, cheap to copy. The tenant prefix (default `bevel_`) lets the
-// auth middleware route key-vs-JWT requests without parsing both shapes.
+// brute force, cheap to copy. The prefix lets the auth middleware route
+// key-vs-JWT requests without parsing both shapes.
 const TOKEN_BYTES = 32;
 
 const MAX_LABEL_LEN = 200;
 
 export class ExternalApiKeyService implements IExternalApiKeyService {
+  private readonly prefixes: readonly string[];
+
   /**
    * @param keyPrefix Tenant-derived plaintext prefix (e.g. `bevel_`) — injected
    *   from {@link AppConfig.externalApiKeyPrefix} so a deploy can brand its keys.
+   *   Every key of the default kind is minted with it.
+   * @param kinds Other kinds a key may be minted as, each with the plaintext
+   *   prefix that kind is spelled with — a Claude link's `gho_`, the shape
+   *   claude.ai expects from a GitHub host. Same key, same table, same
+   *   revocation; the KIND is stored on the row and is what tells such keys
+   *   apart (a label is the person's to edit), the prefix is only what the
+   *   outside world sees and what routes the bearer back here.
    */
   constructor(
     private readonly db: Database,
     private readonly keyPrefix: string,
-  ) {}
+    private readonly kinds: Readonly<Record<string, string>> = {},
+  ) {
+    this.prefixes = [keyPrefix, ...Object.values(kinds)];
+  }
 
-  /** True if a bearer string carries this tenant's external-API-key prefix. */
+  /** True if a bearer string carries one of this service's key prefixes. */
   looksLikeExternalApiKey(token: string): boolean {
-    return typeof token === 'string' && token.startsWith(this.keyPrefix);
+    return typeof token === 'string' && this.prefixes.some((p) => token.startsWith(p));
   }
 
-  async mint(userId: string, label: string): Promise<MintedExternalApiKey> {
+  async mint(userId: string, label: string, options: MintOptions = {}): Promise<MintedExternalApiKey> {
+    const kind = options.kind ?? DEFAULT_KEY_KIND;
+    const prefix = kind === DEFAULT_KEY_KIND ? this.keyPrefix : this.kinds[kind];
+    if (!prefix) throw new Error(`Unknown key kind "${kind}"`);
     const trimmed = (label ?? '').trim();
     if (trimmed.length === 0) {
       throw new InvalidTokenLabelError('Label cannot be empty');
@@ -48,12 +65,12 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       );
     }
 
-    const plaintext = this.keyPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
+    const plaintext = prefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const tokenHash = hashToken(plaintext);
 
     const [row] = await this.db
       .insert(externalApiKeys)
-      .values({ userId, tokenHash, label: trimmed })
+      .values({ userId, tokenHash, label: trimmed, kind })
       .returning();
 
     return {
@@ -202,6 +219,7 @@ function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySumm
   return {
     id: row.id,
     label: row.label,
+    kind: row.kind,
     createdAt: row.createdAt.getTime(),
     lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
     revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,

package/src/modules/tool-manuals/__tests__/mcp-json-discovery.test.ts

@@ -1,8 +1,31 @@
 import { describe, expect, it, vi, afterEach } from 'vitest';
-import { descriptorsFromMcpJson } from '../mcp-json-discovery.js';
+import { descriptorsFromMcpJson, judgeMcpServerEntry } from '../mcp-json-discovery.js';
 
 afterEach(() => vi.restoreAllMocks());
 
+describe('judgeMcpServerEntry', () => {
+  it('keeps every accepted header and env key — one spelled __proto__ included', () => {
+    // Parsed from text, as a repository file is: JSON.parse makes `__proto__`
+    // an own key, and a plain-object copy would turn it into a prototype
+    // assignment and lose it.
+    const http = judgeMcpServerEntry(
+      'vendor',
+      JSON.parse('{"type":"streamable-http","url":"https://x.example","headers":{"__proto__":"p","X-A":"a"}}'),
+    );
+    expect(http.ok).toBe(true);
+    if (!http.ok || http.transport !== 'streamable-http') throw new Error('unreachable');
+    expect(Object.keys(http.entry.headers ?? {}).sort()).toEqual(['X-A', '__proto__']);
+    expect(http.entry.headers?.['__proto__']).toBe('p');
+
+    const stdio = judgeMcpServerEntry(
+      'launch',
+      JSON.parse('{"type":"stdio","command":"run","env":{"__proto__":"p"}}'),
+    );
+    if (!stdio.ok || stdio.transport !== 'stdio') throw new Error('unreachable');
+    expect(stdio.entry.env?.['__proto__']).toBe('p');
+  });
+});
+
 const MANIFEST = JSON.stringify({
   name: 'gtm',
   extensions: {

package/src/modules/tool-manuals/__tests__/tool-manuals.cli.test.ts

@@ -192,6 +192,8 @@ describe('manual namespaces are unique, not merely manual names', () => {
    */
   async function writeMcpServer(folder: string, serverName: string): Promise<void> {
     await mkdir(join(pluginsDir(), folder), { recursive: true });
+    // A plugin is a folder with a manifest; the servers ride in its mcp.json.
+    await writeFile(join(pluginsDir(), folder, 'plugin.json'), `{"name":"${folder.toLowerCase()}"}`);
     await writeFile(
       join(pluginsDir(), folder, 'mcp.json'),
       JSON.stringify({ mcpServers: { [serverName]: { type: 'streamable-http', url: 'https://v.example/mcp' } } }),