@bevel-software/platform-core-backend 0.21.0 → 0.22.0

package/src/modules/plugins/join-requests.service.ts

@@ -9,6 +9,13 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
 import type { KbContext } from '../../shared/kb-context.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import {
+  rulesFileFor,
+  type AccessRequestTarget,
+  type IAccessRequestLifecycle,
+} from '../access/access-requests.contract.js';
+import type { Verb } from '../access-model/access-grammar.js';
 import { pendingProposals, type JoinProposal } from './join-proposals.js';
 
 /** One open join change request, with what it still proposes. */
@@ -22,57 +29,185 @@ export interface JoinRequest {
 }
 
 /**
- * Join requests as PROPOSALS, and the reconciliation that retires them.
+ * Access requests as PROPOSALS, and the reconciliation that retires them.
  *
  * The lifecycle has no state of its own — it is derived, every time, from two
- * copies of one file:
+ * copies of one file (a folder's `access.md`, or a file's own frontmatter):
  *
- *   open        the branch's `access.md` grants something the default's does not
+ *   open        the branch proposes something the person does not already hold
  *   settled     it does not
  *
- * so "approve" is not an operation on the request at all. A manager grants a
+ * so "approve" is not an operation on the request at all. An editor grants a
  * principal through the ordinary access path (the same lock + commit every
  * other access edit uses, gated the same way), the default branch gains that
- * entry, and the proposal stops being pending because the diff no longer
- * contains it. When the last one goes, the change request has nothing left to
- * say and is rejected, its branch deleted.
+ * entry, and the proposal stops being pending.
+ *
+ * "Does not already hold" is stronger than "is not in the file", and
+ * deliberately so: Owner covers Can edit, a parent folder's grant covers this
+ * one, and a role or group carries access without naming anybody. Each of
+ * those would leave a proposal nobody can usefully accept — accepting writes
+ * a grant that changes nothing — and the request would sit open forever. See
+ * {@link JoinRequestsService.unmetProposals}.
  *
- * That reconciliation runs LAZILY on every listing as well as on demand, so a
- * grant made anywhere — this banner, the Manage-access dialog, a hand edit —
- * settles the request that asked for it. Nothing has to remember to.
+ * That reconciliation runs LAZILY on every listing as well as on demand, so
+ * access gained anywhere — this banner, the Manage access dialog, a hand
+ * edit, a role someone joined — settles the request that asked for it.
+ * Nothing has to remember to.
  */
-export class JoinRequestsService {
+export class JoinRequestsService implements IAccessRequestLifecycle {
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly workflow: IWorkflowService,
     private readonly kb: Pick<KbContext, 'defaultBranch' | 'defaultWorkspaceId'>,
+    /**
+     * Read-only, and asked one question only: does this person already hold
+     * this verb on the item, on the DEFAULT branch? See {@link unmetProposals}.
+     */
+    private readonly accessControl: Pick<
+      IAccessControl,
+      'canRead' | 'canWrite' | 'canOwner' | 'canDownload'
+    >,
   ) {}
 
   /**
-   * Open join requests for `plugin`, each carrying only its still-pending
-   * proposals. Requests with none left are reconciled away (rejected, branch
-   * deleted) and omitted.
+   * What `branch` still proposes for `target`, minus everything the person it
+   * names already holds — or NULL when the branch's own copy could not be read
+   * at all.
+   *
+   * That distinction is the whole point of the return type. "The branch says
+   * nothing" is NOT "the branch proposes nothing", and the two arrive as the
+   * same empty diff: `pendingProposals` reads an unreadable file as carrying
+   * no grants (fail-closed, which is right for deciding what to SHOW). Used as
+   * the settle test it is fail-open in the one direction that cannot be taken
+   * back — it closes a request nobody answered.
+   *
+   * And unreadable is the normal case for a few seconds. These reads go
+   * through `origin/<branch>` in the DEFAULT branch's clone, whose fetch is
+   * throttled; a request opened moments ago names a ref that clone has not
+   * heard of. So a miss is retried behind a FORCED fetch before it is believed,
+   * and if it still misses the caller is told nothing rather than something
+   * false.
+   */
+  async proposalsOn(
+    branch: string,
+    target: AccessRequestTarget,
+    opts: { fresh?: boolean } = {},
+  ): Promise<JoinProposal[] | null> {
+    const rulesPath = rulesFileFor(target);
+    await this.refresh({ force: opts.fresh });
+    let branchText = await this.readAt(branch, rulesPath);
+    if (branchText === null && !opts.fresh) {
+      await this.refresh({ force: true });
+      branchText = await this.readAt(branch, rulesPath);
+    }
+    if (branchText === null) return null;
+    // `kind` picks the grammar: a folder's rules are block lists in an
+    // access.md body, a file's are its own frontmatter, where one grant is
+    // written as a scalar. Reading one with the other's grammar yields no
+    // grants, which reads as a finished request.
+    const proposals = pendingProposals(
+      branchText,
+      await this.readAt(this.kb.defaultBranch, rulesPath),
+      rulesPath,
+      target.kind,
+    );
+    // Unreadable rules on the branch: say nothing rather than "nothing left".
+    if (proposals === null) return null;
+    return this.unmetProposals(proposals, target);
+  }
+
+  /**
+   * Drop every proposal the live workspace has already ANSWERED, however it
+   * was answered.
+   *
+   * The file diff alone cannot see this. A request asking for `write` is
+   * satisfied by an `owner:` line, by a grant on a parent folder, or by a role
+   * or group the person has since joined — none of which put their email into
+   * this file, so the diff keeps reporting a proposal nobody can usefully
+   * accept (accepting writes a grant that changes nothing, and the request
+   * never retires). Asking the resolver the question the dialog's own grant
+   * would have to satisfy closes those requests instead of stranding them.
    *
-   * `actor` is who the reconciliation acts as — a manager of the plugin, since
+   * A proposal naming a ROLE keeps the literal rule: "does this role hold the
+   * verb here" is not a question the per-person resolver answers, and a role
+   * proposal is answered by the live rules carrying it.
+   */
+  private async unmetProposals(
+    proposals: JoinProposal[],
+    target: AccessRequestTarget,
+  ): Promise<JoinProposal[]> {
+    const out: JoinProposal[] = [];
+    for (const proposal of proposals) {
+      if (proposal.principal.kind !== 'user') {
+        out.push(proposal);
+        continue;
+      }
+      if (await this.holds(proposal.principal.email, proposal.verb, target.path)) continue;
+      out.push(proposal);
+    }
+    return out;
+  }
+
+  /**
+   * Does `email` hold `verb` on the ITEM, on the default branch? The verb
+   * folds are the resolver's own (owner covers write, write covers read), so
+   * this asks exactly what an accepted grant would have to achieve.
+   *
+   * Best-effort in ONE direction: a resolver that fails answers "no", which
+   * leaves the request open. A failure must never close somebody's request for
+   * them.
+   */
+  private async holds(email: string, verb: Verb, itemPath: string): Promise<boolean> {
+    const wsId = this.kb.defaultWorkspaceId();
+    try {
+      switch (verb) {
+        case 'owner':
+          return await this.accessControl.canOwner(wsId, email, itemPath);
+        case 'write':
+          return await this.accessControl.canWrite(wsId, email, itemPath);
+        case 'download':
+          return await this.accessControl.canDownload(wsId, email, itemPath);
+        default:
+          return await this.accessControl.canRead(wsId, email, itemPath);
+      }
+    } catch (err) {
+      log.warn(
+        `could not resolve ${verb} on "${itemPath}" for a request: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Open requests for one item, each carrying only what it still proposes.
+   * Requests with nothing left are reconciled away (rejected, branch deleted)
+   * and omitted.
+   *
+   * `key` is what named the branch (`joinBranchFor`) — a plugin's name for a
+   * Subscribe request, the item's own path for everything the Manage access
+   * dialog opens. `target` is the item whose rules those proposals edit; the
+   * two differ only for plugins, whose folder is not their name.
+   *
+   * `actor` is who the reconciliation acts as — an editor of the item, since
    * rejecting a change request requires write on everything it touches.
    */
   async list(
-    plugin: string,
-    folder: string,
+    key: string,
+    target: AccessRequestTarget,
     crs: ChangeRequest[],
     actor: AuthUser,
   ): Promise<JoinRequest[]> {
-    await this.refresh();
-    const accessPath = `${folder}/access.md`;
-    const baseText = await this.readAt(this.kb.defaultBranch, accessPath);
     const out: JoinRequest[] = [];
     for (const cr of crs) {
-      if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, plugin)) continue;
-      const proposals = pendingProposals(
-        await this.readAt(cr.branch, accessPath),
-        baseText,
-        accessPath,
-      );
+      if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, key)) continue;
+      const proposals = await this.confirmedProposals(cr.branch, target);
+      // Unreadable: leave it exactly as it is. There is nothing to offer an
+      // editor and nothing that says it is finished, and closing it on a read
+      // that failed would end somebody's request for them. It stays in Change
+      // requests for you, where it can still be answered by hand.
+      if (proposals === null) continue;
       if (proposals.length === 0) {
         await this.settle(cr, actor);
         continue;
@@ -94,24 +229,46 @@ export class JoinRequestsService {
    * same round-trip instead of waiting for the next listing.
    */
   async reconcile(
-    plugin: string,
-    folder: string,
+    key: string,
+    target: AccessRequestTarget,
     cr: ChangeRequest,
     actor: AuthUser,
   ): Promise<boolean> {
-    if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, plugin)) return false;
-    await this.refresh();
-    const accessPath = `${folder}/access.md`;
-    const proposals = pendingProposals(
-      await this.readAt(cr.branch, accessPath),
-      await this.readAt(this.kb.defaultBranch, accessPath),
-      accessPath,
-    );
-    if (proposals.length > 0) return false;
+    if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, key)) return false;
+    const proposals = await this.confirmedProposals(cr.branch, target);
+    // Same rule as the listing: only a branch that was READ and, on a fresh
+    // read, proposes nothing is finished.
+    if (proposals === null || proposals.length > 0) return false;
     await this.settle(cr, actor);
     return true;
   }
 
+  /**
+   * What the branch proposes, with an EMPTY answer confirmed against freshly
+   * fetched refs before anyone acts on it. Null keeps its meaning: nothing
+   * could be read, so nothing can be said.
+   *
+   * The confirmation is there because an empty answer is the terminal one.
+   * These reads go through `origin/<branch>` in the default branch's clone,
+   * and that clone's fetch is throttled — so a branch whose remote-tracking
+   * ref is a few seconds old answers with the commit BEFORE the proposal was
+   * pushed. That is a file identical to live, which is an empty diff, which
+   * reads as "every grant has landed". A request nobody answered is then
+   * closed, its branch deleted, and the person told it was not accepted.
+   *
+   * One extra fetch, on the one path that cannot be undone — and when that
+   * fetch turns up a proposal after all, it is the answer, not a discarded
+   * second opinion.
+   */
+  private async confirmedProposals(
+    branch: string,
+    target: AccessRequestTarget,
+  ): Promise<JoinProposal[] | null> {
+    const first = await this.proposalsOn(branch, target);
+    if (first === null || first.length > 0) return first;
+    return this.proposalsOn(branch, target, { fresh: true });
+  }
+
   /**
    * Close a request whose proposals have all landed, and delete its branch.
    *
@@ -180,10 +337,13 @@ export class JoinRequestsService {
    * Refresh remote-tracking refs before reading them. Throttled inside, and
    * best-effort: a request pushed seconds ago is worth one fetch, but a fetch
    * failure must degrade to "read what we have" rather than empty the list.
+   *
+   * `force` skips the throttle — for the one caller that has already missed
+   * and must not mistake a stale ref list for an answer.
    */
-  private async refresh(): Promise<void> {
+  private async refresh(opts: { force?: boolean } = {}): Promise<void> {
     await this.workspaceService
-      .ensureRemotesFetched(this.kb.defaultWorkspaceId())
+      .ensureRemotesFetched(this.kb.defaultWorkspaceId(), opts)
       .catch(() => undefined);
   }
 }

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

@@ -19,6 +19,7 @@ import { PluginProvisionError, type PluginProvisionService } from './plugin-prov
 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 { folderTarget } from '../access/access-requests.contract.js';
 import type { PluginJoinRequestJobs } from './join-request-jobs.service.js';
 import type { JoinRequestRecord } from './join-request-records.store.js';
 import type {
@@ -619,7 +620,7 @@ export function createPluginsRoutes(
       if (!ctx) return;
       const crs = await workflow.listChangeRequests();
       res.json({
-        requests: await joinRequests.list(joinKeyOf(ctx.plugin), ctx.folder, crs, ctx.user),
+        requests: await joinRequests.list(joinKeyOf(ctx.plugin), folderTarget(ctx.folder), crs, ctx.user),
       });
     } catch (err) {
       log.error('failed to list join requests:', { err });
@@ -649,7 +650,7 @@ export function createPluginsRoutes(
         res.status(404).json({ error: 'Not found' });
         return;
       }
-      res.json({ closed: await joinRequests.reconcile(joinKeyOf(ctx.plugin), ctx.folder, cr, ctx.user) });
+      res.json({ closed: await joinRequests.reconcile(joinKeyOf(ctx.plugin), folderTarget(ctx.folder), cr, ctx.user) });
     } catch (err) {
       log.error('failed to reconcile a join request:', { err });
       res.status(500).json({ error: 'Failed to update the request' });

package/src/modules/settings/__tests__/repository-source.test.ts

@@ -0,0 +1,191 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { ManagedRepository, MANAGED_REPOSITORY_DIR } from '../managed-repository.js';
+import { RepositorySource, type GitHubAppRepository } from '../repository-source.js';
+
+let root: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-managed-'));
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+const reading = (values: Record<string, string>) => (key: string) => values[key] ?? '';
+
+function source(values: Record<string, string>, extra: { fallbackToken?: string; githubApp?: GitHubAppRepository } = {}) {
+  const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+  return {
+    managed,
+    source: new RepositorySource({
+      read: reading(values),
+      fallback: { username: 'x-access-token', token: extra.fallbackToken ?? '' },
+      managed,
+      ...(extra.githubApp ? { githubApp: extra.githubApp } : {}),
+    }),
+  };
+}
+
+const HOSTED = { kbRepoUrl: 'https://git.example.com/acme/kb.git', gitToken: 'the-token', gitUsername: 'oauth2' };
+
+describe('RepositorySource: which way a deployment has its repository', () => {
+  it('has none while nothing is configured', () => {
+    const { source: s } = source({});
+    expect(s.mode()).toBeNull();
+    expect(s.url()).toBe('');
+    expect(s.answered()).toBe(false);
+    expect(s.credentials.token()).toBeNull();
+  });
+
+  it('reads a deployment configured before there was a choice as what it has: an address and a token', () => {
+    const { source: s } = source(HOSTED);
+    expect(s.mode()).toBe('token');
+    expect(s.url()).toBe(HOSTED.kbRepoUrl);
+    expect(s.credentials.token()).toBe('the-token');
+    expect(s.credentials.username()).toBe('oauth2');
+    expect(s.answered()).toBe(true);
+  });
+
+  it('reads a token the environment spells the old way', () => {
+    const { source: s } = source({ kbRepoUrl: HOSTED.kbRepoUrl }, { fallbackToken: 'from-GITHUB_TOKEN' });
+    expect(s.mode()).toBe('token');
+    expect(s.credentials.token()).toBe('from-GITHUB_TOKEN');
+    expect(s.answered()).toBe(true);
+  });
+
+  it('is not answered by half of an address and a token', () => {
+    expect(source({ kbRepoUrl: HOSTED.kbRepoUrl }).source.answered()).toBe(false);
+    expect(source({ gitToken: 'the-token' }).source.answered()).toBe(false);
+  });
+
+  it('ignores a mode it does not know, and reads what is configured', () => {
+    expect(source({ ...HOSTED, gitMode: 'carrier-pigeon' }).source.mode()).toBe('token');
+  });
+
+  it('answers for the values a save would put in effect, without the save', () => {
+    const { source: s, managed } = source(HOSTED);
+    const after = reading({ ...HOSTED, gitMode: 'managed' });
+    expect(s.mode(after)).toBe('managed');
+    expect(s.url(after)).toBe(managed.path);
+    // What is in effect has not moved.
+    expect(s.mode()).toBe('token');
+  });
+});
+
+describe('RepositorySource: a repository the deployment keeps', () => {
+  it('is reached by its path, and presented nothing', () => {
+    const { source: s, managed } = source({ gitMode: 'managed' });
+    expect(s.url()).toBe(managed.path);
+    expect(s.url()).toBe(path.join(root, 'managed-repository', MANAGED_REPOSITORY_DIR));
+    expect(s.answered()).toBe(true);
+    expect(s.credentials.token()).toBeNull();
+  });
+
+  /**
+   * One mode's credential is never presented to another mode's repository.
+   * A deployment that moved still has its old token stored, and it must not
+   * ride along in the environment of every git call made against a folder.
+   */
+  it('is never presented the token of the repository the deployment had before', () => {
+    const { source: s } = source({ ...HOSTED, gitMode: 'managed' }, { fallbackToken: 'from-the-environment' });
+    expect(s.credentials.token()).toBeNull();
+    expect(s.credentials.username()).toBe('x-access-token');
+  });
+});
+
+describe('RepositorySource: a repository reached through a GitHub App', () => {
+  const app = (overrides: Partial<GitHubAppRepository> = {}): GitHubAppRepository => ({
+    url: () => 'https://github.com/acme/kb.git',
+    token: () => 'an-installation-token',
+    prepare: async () => undefined,
+    answered: () => true,
+    ...overrides,
+  });
+
+  it('asks the app for the address and the token', () => {
+    const { source: s } = source({ gitMode: 'github-app', gitToken: 'a-leftover' }, { githubApp: app() });
+    expect(s.url()).toBe('https://github.com/acme/kb.git');
+    expect(s.credentials.token()).toBe('an-installation-token');
+    expect(s.credentials.username()).toBe('x-access-token');
+    expect(s.answered()).toBe(true);
+  });
+
+  it('renews the token before git is run, and only in this mode', async () => {
+    let renewed = 0;
+    const githubApp = app({ prepare: async () => void (renewed += 1) });
+    await source({ gitMode: 'github-app' }, { githubApp }).source.credentials.prepare?.();
+    await source(HOSTED, { githubApp }).source.credentials.prepare?.();
+    await source({ gitMode: 'managed' }, { githubApp }).source.credentials.prepare?.();
+    expect(renewed).toBe(1);
+  });
+
+  it('is unanswered on a deployment that has no such app', () => {
+    const { source: s } = source({ gitMode: 'github-app' });
+    expect(s.answered()).toBe(false);
+    expect(s.url()).toBe('');
+    expect(s.credentials.token()).toBeNull();
+  });
+});
+
+describe('ManagedRepository', () => {
+  const runner = new NodeGitRunner(30_000);
+  const git = async (cwd: string, ...args: string[]) => (await runner.run(cwd, args)).stdout.trim();
+
+  it('is created empty, bare, on the branch it is given', async () => {
+    const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+    expect(await managed.exists()).toBe(false);
+    await managed.ensure(runner, 'trunk');
+    expect(await managed.exists()).toBe(true);
+    expect(await git(managed.path, 'rev-parse', '--is-bare-repository')).toBe('true');
+    expect(await git(managed.path, 'symbolic-ref', 'HEAD')).toBe('refs/heads/trunk');
+    expect(await git(managed.path, 'for-each-ref')).toBe('');
+  });
+
+  it('is cloned from, pushed to and fetched from like any remote', async () => {
+    const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+    await managed.ensure(runner);
+    const one = path.join(root, 'one');
+    await fs.mkdir(one);
+    await git(one, 'init', '--initial-branch=main');
+    await fs.writeFile(path.join(one, 'README.md'), 'hello\n');
+    await git(one, 'add', '.');
+    await git(one, '-c', 'user.name=t', '-c', 'user.email=t@example.test', 'commit', '-m', 'first');
+    await git(one, 'push', managed.path, 'main');
+
+    const two = path.join(root, 'two');
+    await git(root, 'clone', '-b', 'main', managed.path, two);
+    // Whatever this machine's git makes of line endings on checkout.
+    expect((await fs.readFile(path.join(two, 'README.md'), 'utf8')).replace(/\r\n/g, '\n')).toBe('hello\n');
+    expect(await git(two, 'config', '--get', 'remote.origin.url')).toBe(managed.path);
+  });
+
+  it('is left exactly as it is when it already exists', async () => {
+    const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+    await managed.ensure(runner);
+    const work = path.join(root, 'work');
+    await fs.mkdir(work);
+    await git(work, 'init', '--initial-branch=main');
+    await fs.writeFile(path.join(work, 'a.md'), 'a\n');
+    await git(work, 'add', '.');
+    await git(work, '-c', 'user.name=t', '-c', 'user.email=t@example.test', 'commit', '-m', 'first');
+    await git(work, 'push', managed.path, 'main');
+    const before = await git(managed.path, 'for-each-ref');
+
+    await managed.ensure(runner, 'another-branch');
+    expect(await git(managed.path, 'for-each-ref')).toBe(before);
+    expect(await git(managed.path, 'symbolic-ref', 'HEAD')).toBe('refs/heads/main');
+  });
+
+  it('refuses a folder that holds something that is not a repository', async () => {
+    const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+    await fs.mkdir(managed.path, { recursive: true });
+    await fs.writeFile(path.join(managed.path, 'somebody.txt'), 'theirs');
+    await expect(managed.ensure(runner)).rejects.toThrow(/is not a git repository/);
+    expect(await fs.readFile(path.join(managed.path, 'somebody.txt'), 'utf8')).toBe('theirs');
+  });
+});