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

package/src/modules/github-app/github-app.routes.ts

@@ -0,0 +1,359 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import { logger } from '../../shared/logging.js';
+import type { DeploymentSettingsService } from '../settings/deployment-settings.service.js';
+import { GitHubAppClient, GitHubAppError } from './github-app.client.js';
+import { repositoriesAsSetting, type GitHubAppConnection } from './github-app.connection.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+
+const log = logger('github-app');
+
+const STATE_COOKIE = 'hexis_github_state';
+const STATE_MAX_AGE_S = 15 * 60;
+/** A GitHub organisation's name, as it appears in an address. */
+const ORGANIZATION_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+/** GitHub refuses an app name longer than this. */
+const MAX_APP_NAME = 34;
+
+export interface GitHubAppRoutesDeps {
+  settings: Pick<DeploymentSettingsService, 'resolve' | 'record'>;
+  connection: GitHubAppConnection;
+  adminAccess: IAdminAccessService;
+  /** Where GitHub sends the browser back to: this deployment's own address. */
+  publicBackendUrl: string;
+  publicFrontendUrl: string;
+  /** Whether the deployment is set up: decides which page a round trip ends on. */
+  isComplete(): boolean;
+  client?: GitHubAppClient;
+}
+
+/** The address GitHub is told to send the browser back to once the app is installed. */
+export function githubAppCallbackUrl(publicBackendUrl: string): string {
+  return `${publicBackendUrl}/api/setup/github-app/callback`;
+}
+
+/**
+ * The manifest a deployment's own GitHub App is created from. It asks for
+ * what the deployment does and nothing else: read and write the contents of
+ * the repositories it is installed on. No webhook, no events, not public:
+ * the app is this deployment's, installed by its owner on the one
+ * repository the knowledge base lives in.
+ */
+export function githubAppManifest(publicBackendUrl: string, publicFrontendUrl: string): Record<string, unknown> {
+  const host = new URL(publicFrontendUrl).host;
+  return {
+    name: `Hexis ${host}`.slice(0, MAX_APP_NAME),
+    url: publicFrontendUrl,
+    description: `Lets the Hexis deployment at ${host} read and write the repository its knowledge base lives in.`,
+    redirect_url: `${publicBackendUrl}/api/setup/github-app/registered`,
+    callback_urls: [githubAppCallbackUrl(publicBackendUrl)],
+    // GitHub then sends the person back signed in, which is what lets the
+    // deployment check that the installation they name is one they hold.
+    request_oauth_on_install: true,
+    public: false,
+    default_permissions: { contents: 'write', metadata: 'read' },
+    default_events: [],
+  };
+}
+
+function readCookie(req: express.Request, name: string): string | null {
+  for (const segment of (req.headers.cookie ?? '').split(';')) {
+    const trimmed = segment.trim();
+    if (!trimmed.startsWith(`${name}=`)) continue;
+    try {
+      return decodeURIComponent(trimmed.slice(name.length + 1)) || null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function same(a: string, b: string): boolean {
+  const left = Buffer.from(a, 'utf8');
+  const right = Buffer.from(b, 'utf8');
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+/**
+ * Connecting a repository on GitHub through a GitHub App, from the setup
+ * screen. Mounted behind the deployment's sign-in; every route is an
+ * admin's.
+ *
+ *   GET  /setup/github-app               where the connection stands
+ *   POST /setup/github-app/manifest      start registering this deployment's own app
+ *   GET  /setup/github-app/registered    GitHub sends the browser back: the app exists
+ *   POST /setup/github-app/install       where on GitHub the app is installed
+ *   POST /setup/github-app/refresh       where to sign in, to read again what may be connected
+ *   GET  /setup/github-app/callback      GitHub sends the browser back: the app is installed
+ *   GET  /setup/github-app/repositories  what the deployment may be pointed at
+ *
+ * A ROUND TRIP IS STARTED BY A POST AND ENDED BY A GET. The two routes
+ * GitHub sends the browser to are ordinary navigations, authenticated by
+ * the session cookie; each checks a state this browser was given when the
+ * round trip started, and spends it. Nothing that starts one is a link, so
+ * a link somebody was sent starts nothing.
+ *
+ * WHAT THE DEPLOYMENT MAY REACH is never taken from the address the browser
+ * came back on. GitHub puts an installation's number there and anyone can
+ * write another: with one app serving many deployments, that number is the
+ * only thing between a deployment and another organisation's repositories.
+ * GitHub sends the person back signed in, and the deployment asks GitHub
+ * two things about THAT PERSON: which installations they reach, and which
+ * repositories of the one they named they can push to with their own
+ * account. The first alone is not enough, since read access to one
+ * repository puts an installation on that list. Only the second is what
+ * the deployment may be pointed at.
+ */
+export function createGitHubAppRoutes(deps: GitHubAppRoutesDeps): express.Router {
+  const router = express.Router();
+  const client = deps.client ?? new GitHubAppClient();
+  const { settings, connection } = deps;
+  const secure = deps.publicBackendUrl.startsWith('https');
+
+  const requireAdmin: express.RequestHandler = async (req, res, next) => {
+    if (!(await deps.adminAccess.isAdmin(req.userEmail))) {
+      res.status(403).json({ error: 'Admins only' });
+      return;
+    }
+    next();
+  };
+
+  /** A state for one round trip, kept in this browser until it comes back. */
+  const beginRoundTrip = (res: express.Response): string => {
+    const tag = settings.resolve('githubAppStateTag');
+    const state = `${tag ? `${tag}.` : ''}${randomBytes(24).toString('base64url')}`;
+    res.cookie(STATE_COOKIE, state, { httpOnly: true, sameSite: 'lax', secure, maxAge: STATE_MAX_AGE_S * 1000, path: '/' });
+    return state;
+  };
+  /** Whether the browser that came back is the one that was sent. */
+  const cameBack = (req: express.Request): boolean => {
+    const kept = readCookie(req, STATE_COOKIE);
+    const given = typeof req.query.state === 'string' ? req.query.state : '';
+    return Boolean(kept && given && same(kept, given));
+  };
+  /** Back to the setup screen, saying how the round trip ended. */
+  const finish = (res: express.Response, outcome: string): void => {
+    const page = deps.isComplete() ? '/deployment' : '/';
+    res.redirect(`${deps.publicFrontendUrl}${page}?github=${encodeURIComponent(outcome)}`);
+  };
+  const installUrl = (slug: string, state: string): string =>
+    `https://github.com/apps/${encodeURIComponent(slug)}/installations/new?state=${encodeURIComponent(state)}`;
+  const outcomeOf = (err: unknown): string =>
+    err instanceof GitHubAppError && err.kind === 'unreachable' ? 'unreachable' : 'refused';
+
+  router.get('/setup/github-app', requireAdmin, (_req, res) => {
+    const credentials = connection.credentials();
+    res.json({
+      // Who supplied the app. Null: this deployment has none yet, and can register its own.
+      registeredBy: connection.registeredBy(),
+      app: credentials ? { slug: credentials.slug, url: `https://github.com/apps/${credentials.slug}` } : null,
+      installation: connection.installationId()
+        ? { id: connection.installationId(), account: settings.resolve('githubInstallationAccount') }
+        : null,
+      repository: settings.resolve('githubRepository') || null,
+    });
+  });
+
+  router.post('/setup/github-app/manifest', requireAdmin, (req, res) => {
+    if (connection.credentials()) {
+      res.status(409).json({ error: 'This deployment already has a GitHub App.' });
+      return;
+    }
+    const organization = (req.body as { organization?: unknown } | undefined)?.organization;
+    const org = typeof organization === 'string' ? organization.trim() : '';
+    if (org && !ORGANIZATION_PATTERN.test(org)) {
+      res.status(400).json({ error: 'Enter the organisation’s name as it appears in its GitHub address.' });
+      return;
+    }
+    const state = beginRoundTrip(res);
+    const base = org ? `https://github.com/organizations/${org}/settings/apps/new` : 'https://github.com/settings/apps/new';
+    // The browser posts the manifest to GitHub itself: a form, not a request of ours.
+    res.json({
+      action: `${base}?state=${encodeURIComponent(state)}`,
+      manifest: githubAppManifest(deps.publicBackendUrl, deps.publicFrontendUrl),
+    });
+  });
+
+  router.get('/setup/github-app/registered', requireAdmin, async (req, res) => {
+    // Spent on return, however the return ends.
+    const returned = cameBack(req);
+    res.clearCookie(STATE_COOKIE, { path: '/' });
+    if (!returned) {
+      finish(res, 'state');
+      return;
+    }
+    const code = typeof req.query.code === 'string' ? req.query.code : '';
+    if (!code || connection.credentials()) {
+      finish(res, code ? 'already-registered' : 'refused');
+      return;
+    }
+    try {
+      const app = await client.convertManifest(code);
+      await settings.record(
+        {
+          githubAppId: app.appId,
+          githubAppSlug: app.slug,
+          githubAppPrivateKey: app.privateKey,
+          githubAppClientId: app.clientId,
+          githubAppClientSecret: app.clientSecret,
+        },
+        req.userId ?? null,
+      );
+      log.info(`GitHub App "${app.slug}" registered for this deployment`, { slug: app.slug, owner: app.owner });
+      // Straight on to installing it: the same round trip, the same state.
+      res.redirect(installUrl(app.slug, beginRoundTrip(res)));
+    } catch (err) {
+      log.error('the GitHub App could not be registered:', { detail: err instanceof Error ? err.message : String(err) });
+      finish(res, outcomeOf(err));
+    }
+  });
+
+  /**
+   * A POST that answers with the address, and the page sends the browser
+   * there. As a link it was a round trip anyone could start in an admin's
+   * browser by getting them to follow it: the state would be set, and
+   * whatever they then installed would come back with a state that matched.
+   */
+  router.post('/setup/github-app/install', requireAdmin, (_req, res) => {
+    const credentials = connection.credentials();
+    if (!credentials) {
+      res.status(409).json({ error: 'This deployment has no GitHub App yet. Create it first.' });
+      return;
+    }
+    res.json({ url: installUrl(credentials.slug, beginRoundTrip(res)) });
+  });
+
+  /**
+   * Ask GitHub again what the person may connect, WITHOUT installing
+   * anything: a sign-in with the app and nothing more, which comes back on
+   * the same callback with a code and no installation named.
+   *
+   * It exists because installing comes back only the first time. Once the
+   * app is installed, the address that installs it opens the installation's
+   * settings on GitHub, and GitHub sends nobody back from there: a
+   * repository added on that page was reached by the app and never offered
+   * here, since what is offered is what was recorded when the person
+   * connected. The same goes for an installation an organisation's owner
+   * approved later, in a browser of their own.
+   */
+  router.post('/setup/github-app/refresh', requireAdmin, (_req, res) => {
+    const credentials = connection.credentials();
+    if (!credentials) {
+      res.status(409).json({ error: 'This deployment has no GitHub App yet. Create it first.' });
+      return;
+    }
+    const state = beginRoundTrip(res);
+    res.json({
+      url: `https://github.com/login/oauth/authorize?client_id=${encodeURIComponent(credentials.clientId)}&state=${encodeURIComponent(state)}`,
+    });
+  });
+
+  router.get('/setup/github-app/callback', requireAdmin, async (req, res) => {
+    const returned = cameBack(req);
+    res.clearCookie(STATE_COOKIE, { path: '/' });
+    if (!returned) {
+      finish(res, 'state');
+      return;
+    }
+    const credentials = connection.credentials();
+    if (!credentials) {
+      finish(res, 'not-registered');
+      return;
+    }
+    // Someone without the right to install asked their organisation's owner
+    // to: nothing is installed yet, and there is nothing to record.
+    if (req.query.setup_action === 'request') {
+      finish(res, 'requested');
+      return;
+    }
+    const code = typeof req.query.code === 'string' ? req.query.code : '';
+    const given = typeof req.query.installation_id === 'string' ? req.query.installation_id : '';
+    if (!code || (given !== '' && !/^\d+$/.test(given))) {
+      finish(res, 'refused');
+      return;
+    }
+    // Back from installing, GitHub names the installation. Back from a
+    // sign-in alone (see `refresh`) it names none, and the one in question
+    // is the one this deployment has. Either way it is only a name: what
+    // decides is what GitHub says the person reaches, below.
+    const refreshing = given === '';
+    const named = given || connection.installationId();
+    try {
+      const userToken = await client.exchangeUserCode(credentials, code);
+      const reached = await client.installationsOf(userToken);
+      let held = named ? reached.find((installation) => installation.id === named) : undefined;
+      if (!named) {
+        // No installation on record and none named: the app was installed
+        // where this browser never came back from (an owner approved it
+        // later). One the person reaches is the one; several are a choice
+        // only installing from here can make.
+        if (reached.length === 0) {
+          finish(res, 'not-installed');
+          return;
+        }
+        if (reached.length > 1) {
+          finish(res, 'several');
+          return;
+        }
+        held = reached[0];
+      }
+      if (!held) {
+        log.warn('an installation was named that the person who came back cannot reach', { installation: named });
+        finish(res, 'not-yours');
+        return;
+      }
+      // Reaching the installation is not holding it: read access to one
+      // repository it covers is enough for GitHub to list it. What the
+      // deployment may be pointed at is what THIS PERSON can push to.
+      const theirs = await client.repositoriesOf(userToken, held.id);
+      const writable = theirs.repositories.filter((repository) => repository.writable).map((r) => r.fullName);
+      if (writable.length === 0) {
+        log.warn('the person who came back can push to nothing the installation covers', { installation: held.id });
+        finish(res, 'nothing-to-write');
+        return;
+      }
+      await settings.record(
+        {
+          githubInstallationId: held.id,
+          githubRepositoriesPermitted: repositoriesAsSetting(writable),
+          ...(held.account ? { githubInstallationAccount: held.account } : {}),
+        },
+        req.userId ?? null,
+      );
+      // A token in hand was another installation's.
+      connection.forget();
+      log.info(
+        refreshing
+          ? `what may be connected through the GitHub App on "${held.account}" was read again`
+          : `GitHub App installed on "${held.account}"`,
+        { installation: held.id, account: held.account, repositories: writable.length },
+      );
+      finish(res, refreshing ? 'refreshed' : 'connected');
+    } catch (err) {
+      log.error('the installation could not be confirmed:', { detail: err instanceof Error ? err.message : String(err) });
+      finish(res, outcomeOf(err));
+    }
+  });
+
+  router.get('/setup/github-app/repositories', requireAdmin, async (_req, res) => {
+    if (!connection.credentials() || !connection.installationId()) {
+      res.status(409).json({ error: 'Connect GitHub first.' });
+      return;
+    }
+    try {
+      res.json(await connection.repositories());
+    } catch (err) {
+      log.error('the repositories could not be listed:', { detail: err instanceof Error ? err.message : String(err) });
+      const unreachable = err instanceof GitHubAppError && err.kind === 'unreachable';
+      res.status(502).json({
+        error: unreachable
+          ? 'GitHub could not be reached. Try again shortly.'
+          : 'GitHub would not list the repositories. The app may have been uninstalled: connect it again.',
+      });
+    }
+  });
+
+  return router;
+}

package/src/modules/github-app/index.ts

@@ -0,0 +1,19 @@
+export {
+  GitHubAppClient,
+  GitHubAppError,
+  appJwt,
+  normalizePrivateKey,
+  type GitHubAppCredentials,
+  type GitHubFailureKind,
+  type Installation,
+  type InstallationRepository,
+  type InstallationToken,
+  type RegisteredApp,
+} from './github-app.client.js';
+export { GitHubAppConnection, repositoriesAsSetting, type GitHubAppConnectionOptions } from './github-app.connection.js';
+export {
+  createGitHubAppRoutes,
+  githubAppCallbackUrl,
+  githubAppManifest,
+  type GitHubAppRoutesDeps,
+} from './github-app.routes.js';

package/src/modules/kb-fs/__tests__/remote-url.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeRepositoryAddress, sameRepository } from '../remote-url.js';
+
+/**
+ * The comparison decides whether a working copy is kept or deleted, so what
+ * it must never do is call the SAME repository a different one.
+ */
+describe('sameRepository', () => {
+  it.each([
+    ['https://github.com/org/repo', 'https://github.com/org/repo.git'],
+    ['https://github.com/org/repo', 'https://github.com/org/repo/'],
+    ['https://github.com/org/repo.git/', 'https://github.com/org/repo'],
+    ['https://GitHub.com/org/repo', 'https://github.com/org/repo'],
+    ['HTTPS://github.com/org/repo', 'https://github.com/org/repo'],
+    ['https://x-access-token:secret@github.com/org/repo', 'https://github.com/org/repo'],
+    ['  https://github.com/org/repo  ', 'https://github.com/org/repo'],
+    ['/srv/git/kb.git', '/srv/git/kb'],
+    ['C:\\git\\kb.git\\', 'C:\\git\\kb'],
+  ])('%s is %s', (a, b) => {
+    expect(sameRepository(a, b)).toBe(true);
+  });
+
+  it.each([
+    ['https://github.com/org/repo', 'https://github.com/org/other'],
+    ['https://github.com/org/repo', 'https://github.com/other/repo'],
+    ['https://github.com/org/repo', 'https://gitlab.com/org/repo'],
+    ['https://github.com/org/repo', 'https://github.com/org/repo-kb'],
+    ['https://github.com/org/Repo', 'https://github.com/org/repo'],
+  ])('%s is not %s', (a, b) => {
+    expect(sameRepository(a, b)).toBe(false);
+  });
+
+  it('never carries a credential into the normalized form', () => {
+    expect(normalizeRepositoryAddress('https://user:token@github.com/org/repo.git')).toBe(
+      'https://github.com/org/repo',
+    );
+  });
+});

package/src/modules/kb-fs/remote-url.ts

@@ -0,0 +1,35 @@
+/**
+ * Whether two repository addresses name the same repository.
+ *
+ * The answer decides whether a working copy on disk is KEPT or DELETED, so it
+ * errs towards "same": only differences that cannot change which repository
+ * is meant are ignored, and they are ignored on both sides.
+ *
+ *  - a trailing slash, and a `.git` suffix — hosts serve both spellings;
+ *  - the letter case of the scheme and the host — DNS does not distinguish;
+ *  - userinfo (`user:token@`) — who asks does not change what is asked for,
+ *    and a credential must never decide, or appear in, a comparison.
+ *
+ * The PATH keeps its case: hosts that fold it and hosts that do not both
+ * exist, and treating `Org/Repo` and `org/repo` as one would keep a clone of
+ * the wrong repository on a host that tells them apart — but deleting a clone
+ * of the right one is the worse error, and an operator who only changed the
+ * case gets a re-clone, not a loss: the work on that clone was pushed to the
+ * same place.
+ */
+export function normalizeRepositoryAddress(address: string): string {
+  let a = address.trim();
+  const url = /^([a-z][a-z0-9+.-]*):\/\/([^/]*)(\/.*)?$/i.exec(a);
+  if (url) {
+    const host = url[2]!.replace(/^[^@]*@/, '').toLowerCase();
+    a = `${url[1]!.toLowerCase()}://${host}${url[3] ?? ''}`;
+  }
+  return a
+    .replace(/[\\/]+$/, '')
+    .replace(/\.git$/i, '')
+    .replace(/[\\/]+$/, '');
+}
+
+export function sameRepository(a: string, b: string): boolean {
+  return normalizeRepositoryAddress(a) === normalizeRepositoryAddress(b);
+}

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

@@ -2,8 +2,13 @@ import { describe, it, expect } from 'vitest';
 import { pendingProposals } from '../join-proposals.js';
 
 /**
- * What a join branch proposes, relative to the default branch. This diff IS
- * the request's lifecycle: non-empty ⇒ open, empty ⇒ settled and closed.
+ * What a request's branch proposes, relative to the default branch. This diff
+ * IS the request's lifecycle: non-empty ⇒ open, empty ⇒ settled and closed,
+ * null ⇒ the branch could not be read and nothing may be concluded.
+ *
+ * Which grammar reads it follows the ITEM, and the second describe below is
+ * why: a folder's rules are block lists in an access.md body, a file's are its
+ * own frontmatter, where a single grant is a scalar.
  */
 const PATH = 'Plugins/GTM/access.md';
 
@@ -17,7 +22,7 @@ describe('pendingProposals', () => {
     const branch = base(
       'read:\n  - GTM Team\n  - Olga Ivanova <olga@bevel.software>\n  - Ali Baba <ali@bevel.software>\n',
     );
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([
       {
         verb: 'read',
         id: 'user:ali@bevel.software',
@@ -31,7 +36,7 @@ describe('pendingProposals', () => {
     // A branch asking for `write` must be visible AS a write request rather
     // than hiding behind "asked to join".
     const branch = base('read:\n  - GTM Team\n  - Olga Ivanova <olga@bevel.software>\nwrite:\n  - Finance Team\n');
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([
       {
         verb: 'write',
         id: 'role:finance team',
@@ -42,12 +47,12 @@ describe('pendingProposals', () => {
   });
 
   it('is EMPTY when the branch is identical — the settled state', () => {
-    expect(pendingProposals(DEFAULT_MD, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(DEFAULT_MD, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
   it('is EMPTY when the branch grants a SUBSET (its proposal already landed)', () => {
     const branch = base('read:\n  - Olga Ivanova <olga@bevel.software>\n');
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
   it('ignores a REMOVAL — a branch that drops one grant but keeps the rest proposes nothing', () => {
@@ -55,36 +60,38 @@ describe('pendingProposals', () => {
     // ordinary change request in the review UI. (Distinct from the subset
     // case above: here GTM Team survives and only Olga is dropped.)
     const branch = base('read:\n  - GTM Team\n');
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
   it('ignores a `deny` entry — a denial is not something to accept', () => {
     const branch = base(
       'read:\n  - GTM Team\n  - Olga Ivanova <olga@bevel.software>\n  - deny Ali Baba <ali@bevel.software>\n',
     );
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
   it('matches principals canonically (case-insensitive email, canonical role)', () => {
     const branch = base('read:\n  - gtm team\n  - Olga I <OLGA@Bevel.Software>\n');
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
   });
 
-  it('treats a MALFORMED branch file as proposing nothing (fail-closed)', () => {
-    // A body naming a verb but shaped wrong is a hard parse error; there is
-    // nothing to offer a manager, and merging is not how this settles anyway.
-    expect(pendingProposals(base('read: GTM Team\n'), DEFAULT_MD, PATH)).toEqual([]);
+  it('says NOTHING about a malformed branch file — not "nothing to propose"', () => {
+    // A body naming a verb but shaped wrong is a hard parse error. The
+    // difference matters because an empty answer CLOSES the request: it has
+    // to mean the branch asks for nothing more, never that it would not say.
+    expect(pendingProposals(base('read: GTM Team\n'), DEFAULT_MD, PATH, 'folder')).toBeNull();
   });
 
-  it('treats a missing branch file as proposing nothing', () => {
-    expect(pendingProposals(null, DEFAULT_MD, PATH)).toEqual([]);
+  it('says NOTHING about a missing branch file either', () => {
+    expect(pendingProposals(null, DEFAULT_MD, PATH, 'folder')).toBeNull();
   });
 
   it('surfaces every branch grant when the DEFAULT file is missing or unreadable', () => {
-    // The safe direction: show the manager proposals to consider rather than
-    // silently swallowing them against an unreadable baseline.
+    // The safe direction on THAT side: show the editor proposals to consider
+    // rather than swallowing them against a baseline nobody could read.
     const branch = base('read:\n  - Ali Baba <ali@bevel.software>\n');
-    expect(pendingProposals(branch, null, PATH)).toHaveLength(1);
+    expect(pendingProposals(branch, null, PATH, 'folder')).toHaveLength(1);
+    expect(pendingProposals(branch, base('read: broken\n'), PATH, 'folder')).toHaveLength(1);
   });
 
   it('does not confuse the SELF-frontmatter with folder rules', () => {
@@ -96,6 +103,80 @@ describe('pendingProposals', () => {
     const branch =
       '---\nread:\n  - everyone\n  - Ali Baba <ali@bevel.software>\n---\n' +
       'read:\n  - GTM Team\n  - Olga Ivanova <olga@bevel.software>\n';
-    expect(pendingProposals(branch, DEFAULT_MD, PATH)).toEqual([]);
+    expect(pendingProposals(branch, DEFAULT_MD, PATH, 'folder')).toEqual([]);
+  });
+});
+
+/**
+ * A FILE's rules are not an access.md. They live in the node's own
+ * frontmatter, and `spliceGrant` writes one grant there as the scalar form
+ * the resolver accepts — `write: Rita <rita@x.io>`, not a list.
+ *
+ * Read with the FOLDER grammar that is a hard parse error ("'write:' must be
+ * a list"), the whole file yields no grants, and a branch with a perfectly
+ * good proposal on it looks like a branch with nothing left to propose. Every
+ * request whose target was a file was closed on the editors' first listing
+ * because of it — before anyone saw the line, let alone pressed Accept.
+ */
+describe('pendingProposals on a FILE, whose rules are its own frontmatter', () => {
+  const FILE = 'Research/Notes.md';
+  const LIVE = '---\nnodeType: "[Note](../NodeTypes/Note.md)"\n---\n# Notes\n\nbody\n';
+  /** Exactly what `spliceGrant(..., { allowScalar: true, target: 'node' })` writes. */
+  const ASKS_WRITE =
+    '---\nnodeType: "[Note](../NodeTypes/Note.md)"\nwrite: Rita Reader <rita@x.io>\n---\n# Notes\n\nbody\n';
+
+  it('reads the scalar grant the splice actually writes', () => {
+    expect(pendingProposals(ASKS_WRITE, LIVE, FILE, 'file')).toEqual([
+      {
+        verb: 'write',
+        id: 'user:rita@x.io',
+        principal: { kind: 'user', email: 'rita@x.io', displayName: 'Rita Reader' },
+        label: 'Rita Reader',
+      },
+    ]);
+  });
+
+  it('is not fooled by the FOLDER grammar, which cannot read it at all', () => {
+    // The regression guard. Before, this answered `[]` — indistinguishable
+    // from a finished request, which is what closed them.
+    expect(pendingProposals(ASKS_WRITE, LIVE, FILE, 'folder')).toBeNull();
+  });
+
+  it('ignores the non-access keys a node legitimately carries', () => {
+    expect(pendingProposals(LIVE, LIVE, FILE, 'file')).toEqual([]);
+    // `nodeType` is not a grant, and its presence is not a parse failure.
+    expect(pendingProposals(LIVE, null, FILE, 'file')).toEqual([]);
+  });
+
+  it('reads a file with no frontmatter as granting nothing, not as unreadable', () => {
+    // Nothing to say is a real answer here; a node need not declare rules.
+    expect(pendingProposals('# Just a note\n', LIVE, FILE, 'file')).toEqual([]);
+  });
+
+  it('says NOTHING about a file whose frontmatter is broken — not "nothing to propose"', () => {
+    // The same rule the folder side keeps: an empty answer closes somebody's
+    // request, so a block that could not be read must not produce one.
+    const neverClosed = '---\nnodeType: "[Note](x)"\nwrite: Rita Reader <rita@x.io>\n# Notes\n\nbody\n';
+    expect(pendingProposals(neverClosed, LIVE, FILE, 'file')).toBeNull();
+    const notAMapping = '---\n- just\n- a list\n---\n# Notes\n';
+    expect(pendingProposals(notAMapping, LIVE, FILE, 'file')).toBeNull();
+    // An empty block is readable, and says nothing.
+    expect(pendingProposals('---\n---\n# Notes\n', LIVE, FILE, 'file')).toEqual([]);
+    // A broken copy on LIVE stays the safe direction: every grant looks incoming.
+    expect(pendingProposals(ASKS_WRITE, neverClosed, FILE, 'file')).toEqual([
+      expect.objectContaining({ verb: 'write', id: 'user:rita@x.io' }),
+    ]);
+  });
+
+  it('reads the list form too, and an Owner request', () => {
+    const asksOwner =
+      '---\nnodeType: "[Note](x)"\nowner:\n  - Rita Reader <rita@x.io>\n---\n# Notes\n';
+    expect(pendingProposals(asksOwner, LIVE, FILE, 'file')).toEqual([
+      expect.objectContaining({ verb: 'owner', id: 'user:rita@x.io' }),
+    ]);
+  });
+
+  it('still settles a file request once the grant is on live', () => {
+    expect(pendingProposals(ASKS_WRITE, ASKS_WRITE, FILE, 'file')).toEqual([]);
   });
 });