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

package/src/modules/access/access.routes.ts

@@ -1,10 +1,11 @@
 import express from 'express';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import { isProtectedBranch, DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { isProtectedBranch, DEFAULT_BRANCH, pluginManifestName } from '@bevel-software/platform-shared';
 import type {
   IAccessControl,
   GrantPrincipal,
   GrantSources,
+  ResolvedPrincipal,
 } from './access-control.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { branchForWorkspaceId, workspaceIdForBranch } from '../../shared/workspace-id.js';
@@ -22,7 +23,10 @@ import {
 import {
   canonicalRoleName,
   EVERYONE_CANONICAL,
+  PLUGIN_TOKEN_PREFIX,
+  PLUGIN_TOKEN_VERBS,
   ROLE_TOKEN_PREFIX,
+  type PluginTokenVerb,
   type Verb,
 } from '../access-model/access-grammar.js';
 import { listAccessDeclarationsUnder } from './access-declarations.js';
@@ -79,20 +83,51 @@ export function createAccessRoutes(
   // accepts — the same principals the admin screens manage, regardless of
   // which branch the caller is viewing. People stay branch-local (the
   // caller's own workspace).
-  const defaultBranchPrincipals = async (): Promise<{ roles: string[]; groups: string[] }> => {
+  const defaultBranchPrincipals = async (): Promise<{
+    roles: string[];
+    groups: string[];
+    plugins: { name: string; folder: string }[];
+  }> => {
     await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
-    const { roles, groups } = await accessControl.kbPrincipals(workspaceIdForBranch(DEFAULT_BRANCH));
-    return { roles, groups };
+    const { roles, groups, plugins } = await accessControl.kbPrincipals(
+      workspaceIdForBranch(DEFAULT_BRANCH),
+    );
+    // `plugins` is defensive: an older resolver double may omit it.
+    return { roles, groups, plugins: plugins ?? [] };
   };
 
   /**
-   * What the mutation routes accept as a principal. `group` exists only at
-   * this boundary: in the access.md entry grammar a group grant is a
-   * bare-name token (bare names resolve GROUP-FIRST, then fall back to the
-   * role), so it is spliced as a role-shaped principal — the separate kind
-   * buys validation against the right namespace and honest 404s.
+   * The plugins `email` may DISCOVER — read the folder's access.md, the same
+   * verdict the plugin index lists on. Both the suggest list and the grant
+   * route go through this, so a plugin hidden from the picker cannot be
+   * named in a grant either, and an undiscoverable one answers exactly like
+   * one that does not exist.
    */
-  type RoutePrincipal = Principal | { kind: 'group'; group: string };
+  const discoverablePlugins = async (
+    email: string,
+    plugins: { name: string; folder: string }[],
+  ): Promise<{ name: string; folder: string }[]> => {
+    if (plugins.length === 0) return [];
+    const verdicts = await accessControl.canReadBatch(
+      workspaceIdForBranch(DEFAULT_BRANCH),
+      email,
+      plugins.map((p) => `${p.folder}/access.md`),
+    );
+    return plugins.filter((p) => verdicts.get(`${p.folder}/access.md`) === true);
+  };
+
+  /**
+   * What the mutation routes accept as a principal. `group` and `plugin`
+   * exist only at this boundary: in the access.md entry grammar a group grant
+   * is a bare-name token (bare names resolve GROUP-FIRST, then fall back to
+   * the role) and a plugin grant is the `plugin/<Name>/<verb>` token, so both
+   * are spliced as role-shaped principals — the separate kinds buy validation
+   * against the right namespace and honest 404s.
+   */
+  type RoutePrincipal =
+    | Principal
+    | { kind: 'group'; group: string }
+    | { kind: 'plugin'; plugin: string; verb: PluginTokenVerb };
 
   /**
    * The role-shaped principal the splice layer actually writes/matches.
@@ -104,6 +139,9 @@ export function createAccessRoutes(
    */
   const asSplicePrincipal = (p: RoutePrincipal): Principal => {
     if (p.kind === 'group') return { kind: 'role', role: p.group };
+    // Written with the folder's own casing; `parseAccessEntry` canonicalises
+    // the name half to the manifest slug on the way back in.
+    if (p.kind === 'plugin') return { kind: 'role', role: `${PLUGIN_TOKEN_PREFIX}${p.plugin.trim()}/${p.verb}` };
     if (p.kind === 'role') {
       const canonical = canonicalRoleName(p.role);
       const bare = canonical.startsWith(ROLE_TOKEN_PREFIX)
@@ -336,7 +374,7 @@ export function createAccessRoutes(
       // Independent lookups batched in ONE Promise.all: the default-branch
       // principals (cached model), the branch-local KB people (cached model),
       // and the users table (only consulted once the query is long enough).
-      const [{ roles, groups }, { people: kbPeople }, userRows] = await Promise.all([
+      const [{ roles, groups, plugins }, { people: kbPeople }, userRows] = await Promise.all([
         defaultBranchPrincipals(),
         accessControl.kbPrincipals(req.params.id),
         q.length >= 2 ? db.select().from(users) : Promise.resolve([]),
@@ -350,6 +388,19 @@ export function createAccessRoutes(
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
+      // Plugins the caller can DISCOVER (read the folder's access.md — the
+      // same verdict the plugin index lists on), so the picker never names a
+      // plugin its enumeration would hide. Their `plugin/<Name>/<verb>`
+      // tokens are built client-side; the name is what a person searches for.
+      const matchedPlugins = (
+        await discoverablePlugins(
+          user.email,
+          plugins.filter((p) => !q || p.name.toLowerCase().includes(q)),
+        )
+      )
+        .map((p) => p.name)
+        .slice(0, CAP);
+
       let people: { name: string; email: string }[] = [];
       if (q.length >= 2) {
         // Union the KB-canonical people with the login-only users table.
@@ -373,6 +424,10 @@ export function createAccessRoutes(
       res.json({
         roles: matchedRoles,
         groups: matchedGroups,
+        // Plugin FOLDER names; each stands for three grantable principals
+        // (`plugin/<Name>/read|write|owner`). Not `plugins` — that key is the
+        // deprecated alias of `roles` below.
+        pluginPrincipals: matchedPlugins,
         people,
         peopleWithheld: q.length < 2,
         // DEPRECATED alias of `roles` — the shipped share dialog still reads
@@ -428,8 +483,19 @@ export function createAccessRoutes(
         throw new AccessMutationError('group principal needs a group name');
       }
       principal = { kind: 'group', group: principalRaw.group };
+    } else if (principalRaw.kind === 'plugin') {
+      if (typeof principalRaw.plugin !== 'string' || !principalRaw.plugin.trim()) {
+        throw new AccessMutationError('plugin principal needs a plugin name');
+      }
+      const verb = principalRaw.verb;
+      if (typeof verb !== 'string' || !(PLUGIN_TOKEN_VERBS as readonly string[]).includes(verb)) {
+        throw new AccessMutationError(
+          `plugin principal needs a verb: one of ${PLUGIN_TOKEN_VERBS.join(', ')}`,
+        );
+      }
+      principal = { kind: 'plugin', plugin: principalRaw.plugin, verb: verb as PluginTokenVerb };
     } else {
-      throw new AccessMutationError("principal.kind must be 'user', 'group', or 'role'");
+      throw new AccessMutationError("principal.kind must be 'user', 'group', 'plugin', or 'role'");
     }
     const targetKind = kind as TargetKind;
     const repoRelTarget = toRepoRelative(rawPath);
@@ -517,12 +583,12 @@ export function createAccessRoutes(
     // non-actionable. Built over the union of every principal in the four
     // eligible lists (kinded `principals`, with the name-only `roles` list as
     // the all-roles fallback).
-    const collectives = new Map<string, { name: string; kind: 'role' | 'group' }>();
+    const collectives = new Map<string, ResolvedPrincipal>();
     for (const list of [eligible, readers, owners, downloaders]) {
       const kinded =
         list.principals ?? list.roles.map((name) => ({ name, kind: 'role' as const }));
       for (const p of kinded) {
-        const key = `${p.kind === 'group' ? 'g' : 'r'}:${p.name.toLowerCase()}`;
+        const key = `${p.kind === 'group' ? 'g' : p.kind === 'plugin' ? 'p' : 'r'}:${p.name.toLowerCase()}`;
         if (!collectives.has(key)) collectives.set(key, p);
       }
     }
@@ -673,6 +739,22 @@ export function createAccessRoutes(
             { kind: 'unknown-group', group: principal.group },
           );
         }
+      } else if (principal.kind === 'plugin') {
+        // A plugin grant must name a plugin the caller can DISCOVER on the
+        // default branch — the same set the suggest list offers, so a plugin
+        // hidden from the picker is refused here with the same words as one
+        // that does not exist. Matched on the manifest slug, the identity the
+        // token canonicalises to.
+        const { plugins } = await defaultBranchPrincipals();
+        const slug = pluginManifestName(principal.plugin);
+        const visible = await discoverablePlugins(user.email, plugins);
+        if (!visible.some((p) => pluginManifestName(p.name) === slug)) {
+          throw new AccessMutationError(
+            `No plugin named "${principal.plugin}". Pick an existing plugin.`,
+            404,
+            { kind: 'unknown-plugin', plugin: principal.plugin },
+          );
+        }
       }
       // Splice shape: group → bare token (group-first precedence); role →
       // explicit `role/<Name>` token (see asSplicePrincipal).

package/src/modules/access-model/__tests__/access-grammar.test.ts

@@ -5,6 +5,7 @@ import {
   registerAccessFrontmatterExtensions,
   accessFrontmatterExtensionList,
   parseOwnAccessEntries,
+  parseRolesYaml,
 } from '../access-grammar.js';
 import { parseGroupsFile } from '../group-files.js';
 
@@ -22,6 +23,23 @@ describe('parseYamlSubset — inline empty collections', () => {
   });
 });
 
+describe("the reserved 'plugin/' prefix — no role or group may pose as a plugin principal", () => {
+  it('parseGroupsFile skips such a group with a warning and keeps the rest', () => {
+    const res = parseGroupsFile('groups:\n  plugin/GTM/read:\n    - mallory@x.io\n  Sales:\n    - sam@x.io\n', 'groups.yaml');
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    expect([...res.groups.keys()]).toEqual(['sales']);
+    expect(res.warnings.some((w) => w.includes("reserved 'plugin/'"))).toBe(true);
+  });
+
+  it('parseRolesYaml refuses such a role outright', () => {
+    const res = parseRolesYaml('roles:\n  Admin:\n    - admin@x.io\n  plugin/GTM/read:\n    - mallory@x.io\n');
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.errors.some((e) => e.includes("reserved 'plugin/'"))).toBe(true);
+  });
+});
+
 describe('parseGroupsFile — empty group sources', () => {
   it('accepts a bare `groups:` as a valid empty set', () => {
     const res = parseGroupsFile('groups:\n', 'groups.yaml');

package/src/modules/access-model/__tests__/plugin-token-canonical.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import {
+  canonicalPluginToken,
+  canonicalRoleName,
+  parseAccessEntry,
+  parsePluginPrincipalKey,
+} from '../access-grammar.js';
+
+/**
+ * ONE spelling for a plugin principal. Every spelling of a token folds to the
+ * same canonical key — through the parser, through the role canonicaliser
+ * that grants and revocations compare with — and a canonical key is exactly
+ * one name and one verb: nothing nested, nothing that is not already a slug.
+ */
+describe('plugin principal tokens — one canonical form', () => {
+  it('folds any spelling of a plugin token to its slugged key', () => {
+    for (const spelling of ['plugin/Sales Team/read', 'plugin/sales-team/read', 'Plugin/SALES TEAM/READ', ' plugin/Sales  Team/read ']) {
+      expect(canonicalPluginToken(spelling)).toBe('plugin/sales-team/read');
+      expect(canonicalRoleName(spelling)).toBe('plugin/sales-team/read');
+    }
+    const parsed = parseAccessEntry('plugin/Sales Team/write');
+    expect(parsed.ok && parsed.entry.kind === 'role' ? parsed.entry.role : null).toBe('plugin/sales-team/write');
+  });
+
+  it('is not a plugin token without a name, with a nested name, or with an unknown verb', () => {
+    for (const bad of ['plugin//read', 'plugin/GTM', 'plugin/GTM/foo/read', 'plugin/GTM/delete', 'role/GTM/read']) {
+      expect(canonicalPluginToken(bad)).toBeNull();
+    }
+    // A non-plugin role still canonicalises the old way.
+    expect(canonicalRoleName('  Sales   Team ')).toBe('sales team');
+  });
+
+  it('accepts as a canonical key only what it would itself generate', () => {
+    expect(parsePluginPrincipalKey('plugin/gtm/read')).toEqual({ slug: 'gtm', verb: 'read' });
+    expect(parsePluginPrincipalKey('plugin/gtm/foo/read')).toBeNull();
+    expect(parsePluginPrincipalKey('plugin/GTM/read')).toBeNull(); // not a slug
+    expect(parsePluginPrincipalKey('plugin/gtm/delete')).toBeNull();
+    expect(parsePluginPrincipalKey('plugin//read')).toBeNull();
+  });
+});

package/src/modules/access-model/access-grammar.ts

@@ -12,6 +12,7 @@
  */
 
 import { parse as parseFullYaml } from 'yaml';
+import { pluginManifestName } from '@bevel-software/platform-shared';
 import type { GroupsIndex } from './group-files.js';
 
 // ---------------------------------------------------------------------------
@@ -86,6 +87,73 @@ export const GROUP_REF_PREFIX = 'group:';
  */
 export const ROLE_TOKEN_PREFIX = 'role/';
 
+/**
+ * PLUGIN-principal token prefix in access.md entries: `plugin/<Name>/<verb>`
+ * names everyone who holds `<verb>` on the plugin folder `Plugins/<Name>` —
+ * `plugin/GTM/read` is the GTM plugin's members, `plugin/GTM/write` its
+ * managers. Membership is DERIVED at model-load time from the plugin's own
+ * `access.md` (see `plugin-principals.ts`), so a grant naming one follows the
+ * plugin's roster with no copying. This is how a shared skill under `Skills/`
+ * is made visible to a plugin: `read: plugin/GTM/read` on the skill folder.
+ *
+ * The name half is canonicalised with the plugin's MANIFEST slug, so
+ * `plugin/Sales Team/read` and `plugin/sales-team/read` are one principal —
+ * the same identity a conformant client keys the plugin on. Reserved in the
+ * group name-safety rules like `role/`.
+ */
+export const PLUGIN_TOKEN_PREFIX = 'plugin/';
+
+/** The verbs a plugin token may name — each is a distinct principal. */
+export const PLUGIN_TOKEN_VERBS = ['read', 'write', 'owner'] as const;
+export type PluginTokenVerb = (typeof PLUGIN_TOKEN_VERBS)[number];
+
+/** The canonical key of a plugin principal, from the plugin's manifest slug. */
+export function pluginPrincipalKey(slug: string, verb: PluginTokenVerb): string {
+  return `${PLUGIN_TOKEN_PREFIX}${slug}/${verb}`;
+}
+
+/**
+ * The parts of a CANONICAL plugin key, or null when the text is not one:
+ * exactly one separator after the prefix, a slug that is its own manifest
+ * slug, one of the three verbs. A generated key never carries a nested
+ * name, so `plugin/a/b/read` is a typo, not a principal.
+ */
+export function parsePluginPrincipalKey(
+  canonical: string,
+): { slug: string; verb: PluginTokenVerb } | null {
+  if (!canonical.startsWith(PLUGIN_TOKEN_PREFIX)) return null;
+  const rest = canonical.slice(PLUGIN_TOKEN_PREFIX.length);
+  const cut = rest.indexOf('/');
+  if (cut <= 0 || rest.indexOf('/', cut + 1) !== -1) return null;
+  const slug = rest.slice(0, cut);
+  if (pluginManifestName(slug) !== slug) return null;
+  const verb = rest.slice(cut + 1);
+  if (!(PLUGIN_TOKEN_VERBS as readonly string[]).includes(verb)) return null;
+  return { slug, verb: verb as PluginTokenVerb };
+}
+
+/**
+ * The canonical key for ANY spelling of a plugin token — `plugin/Sales Team/read`,
+ * `Plugin/sales-team/READ` — or null when the text is not one: a name must be
+ * present and hold no further `/`, the verb must be one of the three. The ONE
+ * place a plugin's spelling folds to its slug: the access-file parser, the
+ * role canonicaliser (which grant and revoke compare through) and the link
+ * service all go through it, so a grant written one way is found again
+ * however it was spelled.
+ */
+export function canonicalPluginToken(token: string): string | null {
+  const body = token.trim();
+  if (!body.toLowerCase().startsWith(PLUGIN_TOKEN_PREFIX)) return null;
+  const rest = body.slice(PLUGIN_TOKEN_PREFIX.length).trim();
+  const cut = rest.lastIndexOf('/');
+  const name = cut > 0 ? rest.slice(0, cut).trim() : '';
+  const verb = cut > 0 ? rest.slice(cut + 1).trim().toLowerCase() : '';
+  if (!name || name.includes('/') || !(PLUGIN_TOKEN_VERBS as readonly string[]).includes(verb)) return null;
+  const slug = pluginManifestName(name);
+  if (!slug) return null;
+  return pluginPrincipalKey(slug, verb as PluginTokenVerb);
+}
+
 export const USER_REF_REGEX = /^(.+?)\s+<\s*([^<>\s]+@[^<>\s]+)\s*>\s*$/;
 export const EMAIL_REGEX = /^[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+$/;
 
@@ -224,9 +292,24 @@ export function hasAccessFrontmatterExtension(p: string): boolean {
 export interface RolesIndex {
   byCanonical: Map<
     string,
-    { displayName: string; emails: Set<string>; groupRefs?: Set<string>; kind?: 'role' | 'group' }
+    {
+      displayName: string;
+      emails: Set<string>;
+      groupRefs?: Set<string>;
+      kind?: 'role' | 'group' | 'plugin';
+      /** For `kind: 'plugin'`: the plugin's identity (its manifest name) the principal derives from. */
+      pluginName?: string;
+      /** For `kind: 'plugin'`: the repo-relative plugin directory, e.g. `Plugins/GTM`. */
+      pluginDir?: string;
+    }
   >;
   byEmail: Map<string, Set<string>>;
+  /**
+   * Principal keys EVERY caller holds, known or not — a plugin whose own
+   * rules grant `everyone` yields a plugin principal no email list can
+   * enumerate. The resolver unions these into every caller's key set.
+   */
+  publicKeys?: Set<string>;
 }
 // ---------------------------------------------------------------------------
 // Tiny YAML subset parser — handles only block mappings + block sequences
@@ -429,7 +512,9 @@ export function bodyAfterFrontmatter(text: string): string {
 // ---------------------------------------------------------------------------
 
 export function canonicalRoleName(name: string): string {
-  return name.trim().toLowerCase().replace(/\s+/g, ' ');
+  // A plugin token canonicalises to its KEY (slugged name), not to its
+  // lowercased spelling — see `canonicalPluginToken`.
+  return canonicalPluginToken(name) ?? name.trim().toLowerCase().replace(/\s+/g, ' ');
 }
 
 export function canonicalEmail(email: string): string {
@@ -482,6 +567,23 @@ export function parseAccessEntry(
     const suffix = canonicalRoleName(role.slice(ROLE_TOKEN_PREFIX.length));
     if (!suffix) return { ok: false, error: `entry '${body}' names no role after '${ROLE_TOKEN_PREFIX}'` };
     role = `${ROLE_TOKEN_PREFIX}${suffix}`;
+  } else if (role.startsWith(PLUGIN_TOKEN_PREFIX)) {
+    // `plugin/<Name>/<verb>`: the name is canonicalised to the plugin's
+    // manifest slug, the verb must be one of the three. Anything else is a
+    // parse error naming the valid shapes — a token that silently resolved to
+    // nothing would be a grant nobody gets and nobody is told about.
+    const key = canonicalPluginToken(body);
+    // Exactly one separator: `plugin/GTM/foo/read` is a typo, not a grant to
+    // some plugin whose slug happens to fold `GTM/foo` into `gtm-foo`.
+    if (key === null) {
+      return {
+        ok: false,
+        error:
+          `entry '${body}' is not a plugin principal — write it as ` +
+          `${PLUGIN_TOKEN_PREFIX}<plugin>/read, ${PLUGIN_TOKEN_PREFIX}<plugin>/write or ${PLUGIN_TOKEN_PREFIX}<plugin>/owner`,
+      };
+    }
+    role = key;
   }
   return { ok: true, entry: { kind: 'role', role, displayRole: body, deny } };
 }
@@ -529,6 +631,16 @@ export function parseRolesYaml(
       );
       continue;
     }
+    // A role spelled `plugin/…` would be overwritten by the synthesised plugin
+    // principal of the same key while its members kept the token — plugin
+    // access for people who are not plugin members. Refused at parse time,
+    // like the group name-safety rule.
+    if (canonical.startsWith(PLUGIN_TOKEN_PREFIX)) {
+      errors.push(
+        `roles.yaml: role '${displayName}' starts with the reserved '${PLUGIN_TOKEN_PREFIX}' prefix — that spelling is the plugin-principal token in access entries`,
+      );
+      continue;
+    }
     if (index.byCanonical.has(canonical)) {
       const prev = index.byCanonical.get(canonical)!.displayName;
       errors.push(

package/src/modules/access-model/group-files.ts

@@ -2,6 +2,7 @@ import {
   EMAIL_REGEX,
   GROUP_REF_PREFIX,
   RESERVED_ROLE_NAMES,
+  PLUGIN_TOKEN_PREFIX,
   ROLE_TOKEN_PREFIX,
   canonicalEmail,
   canonicalRoleName,
@@ -68,6 +69,9 @@ export function unsafeNameReason(displayName: string): string | null {
   if (canonicalRoleName(trimmed).startsWith(ROLE_TOKEN_PREFIX)) {
     return `starts with the reserved '${ROLE_TOKEN_PREFIX}' prefix (the explicit role token in access entries)`;
   }
+  if (canonicalRoleName(trimmed).startsWith(PLUGIN_TOKEN_PREFIX)) {
+    return `starts with the reserved '${PLUGIN_TOKEN_PREFIX}' prefix (the plugin-principal token in access entries)`;
+  }
   return null;
 }
 

package/src/modules/access-model/plugin-principals.ts

@@ -0,0 +1,137 @@
+import { comparePathComponents } from '../../shared/path-order.js';
+import {
+  EVERYONE_CANONICAL,
+  PLUGIN_TOKEN_PREFIX,
+  PLUGIN_TOKEN_VERBS,
+  pluginPrincipalKey,
+  type AccessFile,
+  type PluginTokenVerb,
+  type RolesIndex,
+  type Verb,
+} from './access-grammar.js';
+
+/**
+ * Plugin principals — `plugin/<Name>/<verb>` — synthesised into the principal
+ * index from each plugin folder's own `access.md`, so a grant naming one
+ * resolves exactly like a group grant: the resolver sees a named principal
+ * with member emails and needs no plugin awareness at all.
+ *
+ * WHAT A PLUGIN'S ROSTER IS: the folder-governing rules of
+ * `Plugins/<Name>/access.md` — the file provisioning seeds and the join flow
+ * edits. Three principals per plugin, following the resolver's own superset
+ * convention (write implies read, owner implies both):
+ *
+ *   plugin/<slug>/read    everyone under read, write or owner
+ *   plugin/<slug>/write   everyone under write or owner
+ *   plugin/<slug>/owner   everyone under owner
+ *
+ * The `<slug>` is the manifest slug of the folder (`pluginManifestName`), the
+ * identity `parseAccessEntry` canonicalises a hand-written token to.
+ *
+ * Deliberately NOT membership:
+ *   - the file's frontmatter (`read: everyone` there is DISCOVERABILITY of
+ *     the access.md itself, not membership) — `AccessFile.entries` already
+ *     holds only the folder block;
+ *   - rules inherited from above the plugin folder (the repo root's
+ *     `write: Admin`) — admins reach the skill through those same rules
+ *     anyway, and the roster should be what the plugin's page shows;
+ *   - `deny` entries — a denial subtracts nothing here; a plugin that wants
+ *     someone out removes the grant;
+ *   - other plugin tokens inside a plugin's rules — skipped, so synthesis is
+ *     one pass with no recursion and no cycle to detect.
+ *
+ * `everyone` in a plugin's own rules makes the corresponding principal
+ * PUBLIC: no email list can enumerate it, so its key is recorded in
+ * `index.publicKeys` and the resolver unions those into every caller's set.
+ *
+ * Runs AFTER groups are merged (so role and group entries expand through the
+ * finished index) and BEFORE unknown-role validation (so plugin tokens in
+ * access files count as known).
+ */
+export function synthesizePluginPrincipals(
+  index: RolesIndex,
+  accessFiles: ReadonlyMap<string, AccessFile>,
+  /**
+   * The repo-relative folders that ARE plugins — the ones carrying a
+   * `plugin.json` — each with its IDENTITY (the manifest's name, or the
+   * folder folded into one), as the model loader read them. A plugin is a
+   * folder with a manifest, at any depth; its access.md is its roster.
+   * Nothing else's is.
+   */
+  pluginDirs: ReadonlyMap<string, string>,
+): void {
+  const claimed = new Set<string>();
+  // The same path order discovery walks in, so "first by path" is the same
+  // plugin in both places — see `comparePathComponents`.
+  for (const [dir, slug] of [...pluginDirs].sort(([a], [b]) => comparePathComponents(a, b))) {
+    // Two plugins with one name: discovery keeps the first by path, so do we —
+    // and the claim is made BEFORE looking for a roster, or a first plugin
+    // without rules would leave its slug to a later twin's roster.
+    if (claimed.has(slug)) continue;
+    claimed.add(slug);
+    const file = accessFiles.get(dir);
+    if (!file) continue; // a plugin without rules has no roster
+    for (const verb of PLUGIN_TOKEN_VERBS) {
+      const { emails, everyone } = holdersOf(index, file, verb);
+      const key = pluginPrincipalKey(slug, verb);
+      index.byCanonical.set(key, {
+        displayName: key,
+        emails,
+        kind: 'plugin',
+        pluginName: slug,
+        pluginDir: dir,
+      });
+      for (const email of emails) {
+        let set = index.byEmail.get(email);
+        if (!set) {
+          set = new Set();
+          index.byEmail.set(email, set);
+        }
+        set.add(key);
+      }
+      if (everyone) {
+        index.publicKeys ??= new Set();
+        index.publicKeys.add(key);
+      }
+    }
+  }
+}
+
+/** The verbs whose grants confer `verb` on the plugin (the superset fold). */
+function sourceVerbsFor(verb: PluginTokenVerb): Verb[] {
+  switch (verb) {
+    case 'read':
+      return ['read', 'write', 'owner'];
+    case 'write':
+      return ['write', 'owner'];
+    case 'owner':
+      return ['owner'];
+  }
+}
+
+function holdersOf(
+  index: RolesIndex,
+  file: AccessFile,
+  verb: PluginTokenVerb,
+): { emails: Set<string>; everyone: boolean } {
+  const emails = new Set<string>();
+  let everyone = false;
+  for (const source of sourceVerbsFor(verb)) {
+    for (const entry of file.entries[source]) {
+      if (entry.deny) continue;
+      if (entry.kind === 'user') {
+        emails.add(entry.email);
+        continue;
+      }
+      if (entry.role === EVERYONE_CANONICAL) {
+        everyone = true;
+        continue;
+      }
+      if (entry.role.startsWith(PLUGIN_TOKEN_PREFIX)) continue; // no recursion
+      const record = index.byCanonical.get(entry.role);
+      if (!record) continue; // an unknown role contributes nothing (loadModel warns separately)
+      for (const email of record.emails) emails.add(email);
+    }
+  }
+  return { emails, everyone };
+}

package/src/modules/database/core-schema.ts

@@ -183,6 +183,12 @@ export const externalApiKeys = pgTable('api_tokens', {
   userId: uuid('user_id').notNull().references(() => users.id),
   tokenHash: text('token_hash').notNull().unique(),
   label: text('label').notNull(),
+  /**
+   * What the key was minted as: `key` by hand, or a flow's own kind (a
+   * Claude link). The one fact that tells such keys apart — the label is
+   * free text the person may edit or imitate.
+   */
+  kind: text('kind').default('key').notNull(),
   createdAt: timestamp('created_at').defaultNow().notNull(),
   lastUsedAt: timestamp('last_used_at'),
   revokedAt: timestamp('revoked_at'),
@@ -490,3 +496,51 @@ export const deploymentSettings = pgTable('deployment_settings', {
   updatedBy: uuid('updated_by').references(() => users.id, { onDelete: 'set null' }),
   updatedAt: timestamp('updated_at').defaultNow().notNull(),
 });
+
+/**
+ * What this deployment presents to claude.ai as a "GitHub Enterprise Server"
+ * so that Cowork and claude.ai can add the per-user marketplace: the app id,
+ * client id and secrets an Owner pastes into Claude's admin settings. ONE row,
+ * generated on first use, replaced whole on rotate. Secrets are sealed with
+ * the secrets key, as stored settings are — see
+ * `marketplace/github-facade/github-facade-credentials.service.ts`.
+ */
+export const githubFacadeIdentity = pgTable('github_facade_identity', {
+  id: text('id').primaryKey(),
+  appId: text('app_id').notNull(),
+  clientId: text('client_id').notNull(),
+  /** Sealed. */
+  clientSecret: text('client_secret').notNull(),
+  /** Sealed. */
+  webhookSecret: text('webhook_secret').notNull(),
+  /** Sealed — PKCS#1 PEM. */
+  privateKeyPem: text('private_key_pem').notNull(),
+  publicKeyPem: text('public_key_pem').notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  rotatedAt: timestamp('rotated_at'),
+});
+
+/**
+ * One-time codes the Claude connect flow issues on the consent page and
+ * Anthropic's backend exchanges seconds later — in the database so the
+ * replica that issued a code and the replica asked to exchange it agree.
+ *
+ * Keyed by the PERSON: "one live code per person" is the table's own rule,
+ * not a cleanup's. Issuing upserts their row — the newest code overwrites
+ * the last in one statement — so the table holds at most one row per user,
+ * for as long as the user exists (the row goes with them), and nothing ever
+ * has to sweep it. The client id is data the exchange checks, not part of
+ * the key: the bridge has one client, and a rotated client id must not leave
+ * a dead row behind under the old one. The code's hash is the unique lookup
+ * an exchange uses, spent by a conditional update. See
+ * `marketplace/github-facade/github-facade-codes.store.ts`.
+ */
+export const githubFacadeCodes = pgTable('github_facade_codes', {
+  userId: uuid('user_id').primaryKey().references(() => users.id, { onDelete: 'cascade' }),
+  clientId: text('client_id').notNull(),
+  codeHash: text('code_hash').notNull().unique(),
+  redirectUri: text('redirect_uri').notNull(),
+  expiresAt: timestamp('expires_at').notNull(),
+  consumedAt: timestamp('consumed_at'),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+});