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

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

@@ -830,7 +830,7 @@ describe('/api/plugins routes', () => {
     expect(await res.json()).toEqual({ requests: [] });
     expect(h.joinRequests.list).toHaveBeenCalledWith(
       'GTM',
-      'Plugins/GTM',
+      { path: 'Plugins/GTM', kind: 'folder' },
       expect.anything(),
       expect.objectContaining({ email: ALI }),
     );

package/src/modules/plugins/__tests__/plugins.tools.test.ts

@@ -53,7 +53,8 @@ describe('the creation endpoints behind the key-or-session gate', () => {
   } as never;
   const authService = {
     getUserById: async (id: string) => (id === ALICE.id ? ALICE : null),
-    verifyToken: (t: string) => {
+    // A session is accepted only for an account that is on; Alice's is.
+    resolveSession: async (t: string) => {
       if (t !== 'session-alice') throw new Error('bad token');
       return { userId: ALICE.id, email: ALICE.email };
     },

package/src/modules/plugins/join-proposals.ts

@@ -1,9 +1,12 @@
 import {
   KNOWN_VERBS,
+  ownAccessReadable,
   parseAccessFile,
+  parseOwnAccessEntries,
   type ParsedEntry,
   type Verb,
 } from '../access-model/access-grammar.js';
+import type { TargetKind } from '../access/access-mutation.service.js';
 
 /**
  * What a join branch is PROPOSING, relative to the default branch.
@@ -50,23 +53,75 @@ function identityOf(entry: ParsedEntry): string {
 }
 
 /**
- * Folder rules from one copy of an `access.md`, per verb, grants only.
+ * The per-verb entries one copy of an item's rules declares, or null when the
+ * text could not be read as rules at all.
  *
- * A file that fails to parse yields NO grants. On the branch side that means
- * a malformed proposal offers nothing to accept (fail-closed). On the default
- * side it means every branch grant looks incoming — which is the safe
- * direction too: the manager is shown proposals to consider rather than
- * having them silently swallowed by an unreadable baseline.
+ * THE GRAMMAR FOLLOWS THE ITEM, because there are two of them and the
+ * resolver picks by item as well:
+ *
+ *   folder   a `access.md`, whose folder rules are a BODY of `verb:` block
+ *            lists — `parseAccessFile`, which fails the whole file if a verb
+ *            is not a list.
+ *   file     the node's OWN frontmatter — `parseOwnAccessEntries`, which also
+ *            accepts the single-value scalar form (`write: Rita <r@x.io>`),
+ *            ignores non-access keys like `nodeType:`, and drops a bad entry
+ *            rather than failing the file.
+ *
+ * Reading a file's frontmatter with the FOLDER grammar is what broke every
+ * request whose target was a file: `spliceGrant` writes one grant into a
+ * node's frontmatter as exactly that scalar — the same bytes the dialog's own
+ * grant writes, which the resolver honours — and the folder grammar rejects it
+ * with "'write:' must be a list", failing the parse, yielding no grants, which
+ * reads as a branch with nothing left to propose. The request was then closed
+ * on the editors' first listing, before anyone had seen it.
+ *
+ * Null is reserved for "could not be read": a folder `access.md` that does
+ * not parse, or a file whose frontmatter is broken (never closed, or not a
+ * mapping). A file with no frontmatter, or with frontmatter naming no verb,
+ * is perfectly readable and simply grants nothing. The file grammar's own
+ * null does not tell those apart, so the question is asked separately: a
+ * broken block read as "grants nothing" would close the request on a
+ * reading that failed, the same mistake by another door.
  */
-function grantsByVerb(text: string | null, path: string): Map<Verb, Map<string, ParsedEntry>> {
-  const out = new Map<Verb, Map<string, ParsedEntry>>();
-  for (const verb of KNOWN_VERBS) out.set(verb, new Map());
-  if (text === null) return out;
+function entriesOf(
+  text: string,
+  path: string,
+  kind: TargetKind,
+): Record<Verb, ParsedEntry[]> | null {
+  if (kind === 'file') {
+    return parseOwnAccessEntries(text) ?? (ownAccessReadable(text) ? emptyGrants() : null);
+  }
   const parsed = parseAccessFile(text, path);
-  if (!parsed.ok) return out;
+  return parsed.ok ? parsed.file.entries : null;
+}
+
+function emptyGrants(): Record<Verb, ParsedEntry[]> {
+  const out = {} as Record<Verb, ParsedEntry[]>;
+  for (const verb of KNOWN_VERBS) out[verb] = [];
+  return out;
+}
+
+/** An index that grants nothing — the baseline a copy nobody could read stands in as. */
+function emptyIndex(): Map<Verb, Map<string, ParsedEntry>> {
+  return new Map(KNOWN_VERBS.map((verb) => [verb, new Map<string, ParsedEntry>()]));
+}
+
+/**
+ * Grants only, indexed by canonical identity, from one copy of the rules.
+ * Null in, null out — an unreadable copy is not an empty one.
+ */
+function grantsByVerb(
+  text: string | null,
+  path: string,
+  kind: TargetKind,
+): Map<Verb, Map<string, ParsedEntry>> | null {
+  if (text === null) return null;
+  const entries = entriesOf(text, path, kind);
+  if (entries === null) return null;
+  const out = emptyIndex();
   for (const verb of KNOWN_VERBS) {
     const byId = out.get(verb)!;
-    for (const entry of parsed.file.entries[verb]) {
+    for (const entry of entries[verb]) {
       if (entry.deny) continue;
       byId.set(identityOf(entry), entry);
     }
@@ -75,19 +130,32 @@ function grantsByVerb(text: string | null, path: string): Map<Verb, Map<string,
 }
 
 /**
- * The grants `branchText` adds over `defaultText` — the proposals a manager
- * can accept. Empty ⇒ the branch's rules are a subset of the default's.
+ * The grants `branchText` adds over `defaultText` — the proposals an editor
+ * can accept. Empty ⇒ the branch's rules are a subset of the default's, which
+ * is the settled state.
+ *
+ * NULL when the branch's own copy is absent or unreadable, which is a
+ * different fact entirely and the one this surface keeps getting wrong: an
+ * empty answer closes somebody's request, so it has to mean "the branch asks
+ * for nothing more", never "the branch would not tell us".
+ *
+ * An unreadable DEFAULT copy stays what it was — every branch grant looks
+ * incoming. That is the safe direction on that side: an editor is shown
+ * proposals to consider rather than having them swallowed by a baseline
+ * nobody could read.
  *
- * `path` is only used to label parse errors; both texts are the same file at
- * two refs.
+ * `path` labels parse errors; both texts are the same file at two refs, and
+ * `kind` says which grammar that file is written in.
  */
 export function pendingProposals(
   branchText: string | null,
   defaultText: string | null,
   path: string,
-): JoinProposal[] {
-  const branch = grantsByVerb(branchText, path);
-  const base = grantsByVerb(defaultText, path);
+  kind: TargetKind,
+): JoinProposal[] | null {
+  const branch = grantsByVerb(branchText, path, kind);
+  if (branch === null) return null;
+  const base = grantsByVerb(defaultText, path, kind) ?? emptyIndex();
   const out: JoinProposal[] = [];
   for (const verb of KNOWN_VERBS) {
     const baseIds = base.get(verb)!;

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__/deployment-settings.service.test.ts

@@ -413,6 +413,22 @@ describe('DeploymentSettingsService — validation', () => {
     );
   });
 
+  it('rejects a directory name carrying a line break, which every path is prefixed with', async () => {
+    // The name is joined onto every workspace-relative path, and a line break
+    // in a path is a separator to git's `cat-file --batch` — so a name
+    // carrying one would make the normaliser emit a path it refuses from a
+    // caller. Refused where the name is SET, which is here and at boot.
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    for (const bad of ['kb\nname', 'kb\rname', 'kb\u0000name', 'kb\u007Fname']) {
+      await expect(settings.save({ kbDirName: bad }, null), bad).rejects.toThrow(
+        /Invalid settings/,
+      );
+    }
+    // The ordinary name beside them, so the rule is not simply refusing both.
+    await expect(settings.save({ kbDirName: 'company-brain' }, null)).resolves.toBeTruthy();
+  });
+
   it('rejects a username that would break out of the credential-helper snippet', async () => {
     const { db } = makeDb();
     const settings = new DeploymentSettingsService(db, ENC_KEY);