@bevel-software/platform-core-backend 0.1.0

package/src/core-config.ts

@@ -0,0 +1,257 @@
+import dotenv from 'dotenv';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultKbTemplateDir } from './assets.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.resolve(__dirname, '../../../.env') });
+
+/**
+ * Configuration for the CORE platform: the git-backed workspace/workflow,
+ * skills, tools, secrets vault, access control, and the MCP surface. Contains
+ * NO LLM, connector, or SSO-provider settings — those live on the enterprise
+ * `AppConfig` (config.ts), which extends this class. A core-only deployment
+ * boots from exactly these env vars.
+ */
+export class CoreConfig {
+  readonly port: number;
+  readonly databaseUrl: string;
+  readonly nodeEnv: string;
+  /**
+   * Tenant slug injected into every credential prefix so a deploy can brand its
+   * keys (`<tenant>_…` external API keys, `<tenant>-int_…` internal tokens,
+   * `<tenant>-up_…` upload tokens). Defaults to `bevel`. Changing it on an
+   * existing deployment invalidates previously minted keys/tokens (their
+   * prefix no longer matches), so pick it once. Lowercase alphanumeric only —
+   * `_` and `-` are reserved as prefix separators.
+   */
+  readonly tenantId: string;
+  readonly workspacesRoot: string;
+  /**
+   * Sibling-to-`workspacesRoot` location for the diff-review backup ledger.
+   * Layout mirrors `workspacesRoot` one-to-one: each user's repo lives at
+   * `<workspacesRoot>/<userId>/<repo>/...` and its backup at
+   * `<backupsRoot>/<userId>/<repo>/...`. Default sits next to workspaces so
+   * the two move together when ops point them at a different volume.
+   */
+  readonly backupsRoot: string;
+  /**
+   * Sibling-to-`workspacesRoot` location for `call_tool_chain` spill files —
+   * oversized tool-chain results parked outside any workspace so any agent (in-
+   * process or external over MCP) can read them back via `read_file`. Ephemeral,
+   * never committed, best-effort GC'd on write.
+   */
+  readonly spillRoot: string;
+  readonly jwtSecret: string;
+  readonly testPassword: string;
+  /** Clone/push URL for the KB repo. Any https git host (GitHub, GitLab, Bitbucket, Azure DevOps, self-hosted). */
+  readonly kbRepoUrl: string;
+  /** Directory name the KB lives under inside each user's workspace dir. */
+  readonly kbDirName: string;
+  /**
+   * Username sent in the git-over-HTTPS Basic credential (password = the git
+   * token). All major hosts accept a token as the password but differ on the
+   * username: GitHub `x-access-token` (default), GitLab `oauth2`, Bitbucket
+   * `x-token-auth`, Azure DevOps any non-empty value. Set `GIT_USERNAME` per
+   * host. Restricted to a safe charset because it's interpolated into the
+   * credential-helper shell snippet.
+   */
+  readonly gitUsername: string;
+  /**
+   * Filesystem path to the KB seed template (the `kb-template/` folder shipped
+   * inside this package — see `defaultKbTemplateDir()`). The seeder reads this
+   * to initialise an empty KB remote, and to top-up missing scaffolding on an
+   * existing one. Override with `KB_TEMPLATE_DIR`.
+   */
+  readonly kbTemplateDir: string;
+  /**
+   * Admin emails written into the generated `roles.yaml` when a fresh KB repo is
+   * seeded. Comma/whitespace-separated. A freshly-seeded repo with no Admin is
+   * unusable (access resolution requires ≥1 Admin), so seeding an EMPTY remote
+   * fails fast when this is empty. Not needed once the remote is already seeded.
+   */
+  readonly seedAdminEmails: string[];
+  /**
+   * Ontology-session boundary kill-switch. When true (default), an agent run
+   * that has read across more than one ontology can no longer write. A no-op on
+   * a single-ontology KB. Set `ONTOLOGY_SESSION_BLOCK=false` to disable.
+   *
+   * Stays on CORE config (not `AppConfig`) even though the write BLOCK itself
+   * is an enterprise-registered hook: the flag also switches off the core-owned
+   * touch TRACKING (the gate skips entirely when false — see
+   * `session-ontology.gate.ts`), so it must exist wherever the tracking runs.
+   */
+  readonly ontologySessionBlock: boolean;
+  /**
+   * Password-login toggle for the login screen. Default enabled; set
+   * `LOGIN_PASSWORD=false` to hide the method AND reject `/auth/login`
+   * server-side. SSO methods are separate `AuthProviderPlugin`s wired by the
+   * composition root — their toggles live with their configuration.
+   */
+  readonly loginPasswordEnabled: boolean;
+  /**
+   * Optional allow-list of email domains. When non-empty, ONLY emails whose
+   * domain matches (exactly, or as a subdomain) may log in via ANY method
+   * (shared-password or SSO). Comma/whitespace-separated; empty (default)
+   * allows any email. A leading `@` or `.` on an entry is tolerated, so
+   * `ALLOWED_EMAIL_DOMAINS=bevel.software, example.com` works as expected.
+   */
+  readonly allowedEmailDomains: string[];
+  /**
+   * 32-byte key (hex or base64) for AES-256-GCM encryption of core at-rest
+   * secrets: the secrets-vault values and the MCP OAuth client secrets/tokens.
+   * Read from `SECRETS_ENC_KEY`, falling back to the legacy
+   * `CONNECTOR_CONFIG_ENC_KEY` → `SHAREPOINT_TOKEN_ENC_KEY` chain so existing
+   * deploys keep decrypting without re-keying. Empty = secret values can't be
+   * saved (a clear error surfaces only when a secret is actually written/read).
+   */
+  readonly secretsEncKey: string;
+  /**
+   * Public base URL of THIS backend, used to build OAuth redirect URIs.
+   * Must match a redirect URI registered with the OAuth provider(s).
+   */
+  readonly publicBackendUrl: string;
+  /** Public base URL of the frontend, where callbacks redirect post-login. */
+  readonly publicFrontendUrl: string;
+
+  constructor() {
+    this.port = parseInt(process.env.PORT || '3001', 10);
+    this.databaseUrl = process.env.DATABASE_URL || 'postgresql://bevel:bevel@localhost:5432/bevel';
+    this.nodeEnv = process.env.NODE_ENV || 'development';
+    this.tenantId = (process.env.TENANT_ID || 'bevel').trim().toLowerCase();
+    if (!/^[a-z0-9]+$/.test(this.tenantId)) {
+      throw new Error(
+        `TENANT_ID must be lowercase alphanumeric (no separators); got "${this.tenantId}"`,
+      );
+    }
+    this.workspacesRoot = process.env.WORKSPACES_ROOT || path.resolve(process.cwd(), 'workspaces');
+    this.backupsRoot = process.env.BACKUPS_ROOT || path.resolve(this.workspacesRoot, '..', 'backups');
+    this.spillRoot = process.env.SPILL_ROOT || path.resolve(this.workspacesRoot, '..', 'tool-chain-spills');
+    this.jwtSecret = process.env.JWT_SECRET || '';
+    this.testPassword = process.env.TEST_PASSWORD || '';
+    // No default: the KB repo is deployment-specific, and a wrong fallback
+    // would surface much later as a confusing clone failure. Fail at boot.
+    this.kbRepoUrl = (process.env.KB_REPO_URL || '').trim();
+    if (this.kbRepoUrl === '') {
+      throw new Error(
+        'KB_REPO_URL is required — the https clone/push URL of the git repository that stores your knowledge base.',
+      );
+    }
+    this.kbDirName = process.env.KB_DIR_NAME || 'knowledge-base';
+    // Provider-neutral git token: operators can set GIT_TOKEN (or the legacy
+    // GITHUB_TOKEN / GH_TOKEN). Normalize onto GITHUB_TOKEN — the name the
+    // credential helper and every `$GITHUB_TOKEN` read + redaction use — so all
+    // three work unchanged. GIT_TOKEN takes PRECEDENCE: it's the provider-neutral
+    // name, so setting it must override a stale legacy GITHUB_TOKEN (e.g. when
+    // switching the KB from GitHub to GitLab), not be shadowed by it.
+    const gitToken = process.env.GIT_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (gitToken) process.env.GITHUB_TOKEN = gitToken;
+    this.gitUsername = (process.env.GIT_USERNAME || 'x-access-token').trim();
+    // Interpolated into the credential-helper shell snippet, so reject anything
+    // that isn't a plain token — no quotes, spaces, or shell metacharacters.
+    if (!/^[A-Za-z0-9._-]+$/.test(this.gitUsername)) {
+      throw new Error(
+        `GIT_USERNAME must match [A-Za-z0-9._-]+ (a plain auth username); got "${this.gitUsername}"`,
+      );
+    }
+    // Default: the `kb-template/` folder shipped inside this package (works
+    // both from src/ and compiled dist/ — see assets.ts).
+    this.kbTemplateDir = process.env.KB_TEMPLATE_DIR || defaultKbTemplateDir();
+    this.seedAdminEmails = (process.env.SEED_ADMIN_EMAILS || '')
+      .split(/[\s,]+/)
+      .map((e) => e.trim().toLowerCase())
+      .filter((e) => e.length > 0);
+    this.ontologySessionBlock =
+      (process.env.ONTOLOGY_SESSION_BLOCK ?? 'true').trim().toLowerCase() !== 'false';
+    this.loginPasswordEnabled =
+      (process.env.LOGIN_PASSWORD ?? 'true').trim().toLowerCase() !== 'false';
+    this.allowedEmailDomains = (process.env.ALLOWED_EMAIL_DOMAINS || '')
+      .split(/[\s,]+/)
+      .map((d) => d.trim().toLowerCase().replace(/^[@.]+/, ''))
+      .filter((d) => d.length > 0);
+    this.secretsEncKey = (
+      process.env.SECRETS_ENC_KEY ||
+      process.env.CONNECTOR_CONFIG_ENC_KEY ||
+      process.env.SHAREPOINT_TOKEN_ENC_KEY ||
+      ''
+    ).trim();
+    this.publicBackendUrl = (process.env.PUBLIC_BACKEND_URL || `http://localhost:${this.port}`)
+      .trim()
+      .replace(/\/+$/, '');
+    this.publicFrontendUrl = (process.env.PUBLIC_FRONTEND_URL || 'http://localhost:5173')
+      .trim()
+      .replace(/\/+$/, '');
+    // Parse-validate so a malformed URL fails at boot rather than producing a
+    // broken OAuth redirect later. (We intentionally don't force https / reject
+    // localhost in production: local Docker runs prod mode over http://localhost.)
+    for (const [name, value] of [
+      ['PUBLIC_BACKEND_URL', this.publicBackendUrl],
+      ['PUBLIC_FRONTEND_URL', this.publicFrontendUrl],
+    ] as const) {
+      try {
+        new URL(value);
+      } catch {
+        throw new Error(`${name} is not a valid URL: "${value}"`);
+      }
+    }
+
+    // Validate format now so a typo surfaces at boot, not at first-seed time.
+    // Emptiness is NOT an error here: an already-seeded remote never needs it.
+    for (const email of this.seedAdminEmails) {
+      if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        throw new Error(`SEED_ADMIN_EMAILS contains an invalid email: "${email}"`);
+      }
+    }
+
+    this.validateKbIdentity();
+  }
+
+  /** Prefix for external API keys (connection keys): `<tenant>_`. */
+  get externalApiKeyPrefix(): string {
+    return `${this.tenantId}_`;
+  }
+
+  /** Prefix for in-process internal HMAC tokens: `<tenant>-int_`. */
+  get internalTokenPrefix(): string {
+    return `${this.tenantId}-int_`;
+  }
+
+  /** Prefix for scoped single-use bulk-upload tokens: `<tenant>-up_`. */
+  get uploadTokenPrefix(): string {
+    return `${this.tenantId}-up_`;
+  }
+
+  /** Prefix for MCP OAuth access tokens: `<tenant>-mcp_`. */
+  get mcpOAuthTokenPrefix(): string {
+    return `${this.tenantId}-mcp_`;
+  }
+
+  private validateKbIdentity(): void {
+    // Validate the two KB-identity inputs up front: `kbRepoUrl` (the clone/push
+    // URL) must be a valid https URL, and `kbDirName` (the dir the clone lives
+    // under in each workspace) must be a single safe path segment. A bad value
+    // in either otherwise surfaces much later as a confusing clone/path failure.
+    let parsed: URL;
+    try {
+      parsed = new URL(this.kbRepoUrl);
+    } catch {
+      throw new Error(`KB_REPO_URL is not a valid URL: ${this.kbRepoUrl}`);
+    }
+    if (parsed.protocol !== 'https:') {
+      throw new Error(`KB_REPO_URL must use https://: ${this.kbRepoUrl}`);
+    }
+
+    // Joined with workspace paths via path.join — separators or ".." would let it
+    // escape the workspace dir.
+    if (
+      !this.kbDirName ||
+      this.kbDirName === '.' ||
+      this.kbDirName === '..' ||
+      this.kbDirName.includes('/') ||
+      this.kbDirName.includes('\\') ||
+      path.isAbsolute(this.kbDirName)
+    ) {
+      throw new Error(`KB_DIR_NAME must be a single path segment: ${this.kbDirName}`);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * @bevel-software/platform-core-backend — the open-source core of the Bevel platform:
+ * git-backed knowledge workspace, workflow (branches / change requests /
+ * locks / SSE), skills, tool manuals + registry + auth, secrets vault, access
+ * control, diff/backup ledger, code-mode and the remote MCP surface.
+ *
+ * Composition entry points:
+ *   - `new CoreConfig()`                     — env-driven core configuration
+ *   - `createCoreServices(config, ports)`    — construct every core service
+ *   - `createCoreServer(core, ext, opts)`    — the Express app (fixed mount order)
+ *
+ * Importing this package ALSO applies the global Express `Request`
+ * augmentation (`req.userId` / `req.userEmail` / token payloads) — the
+ * middleware modules re-exported below carry the `declare global` blocks, so
+ * consumers get the augmented types without a side-effect import of their own.
+ *
+ * Finer-grained internals are available via the `./modules/*` subpath exports.
+ */
+
+export { CoreConfig } from './core-config.js';
+export { createCoreServices, type CoreServices } from './core/create-core-services.js';
+export {
+  createCoreServer,
+  type ServerExtensions,
+  type ToolSurfaceCtx,
+} from './core/create-core-server.js';
+export { noopRecoveryAgent, type CorePorts } from './core/core-ports.js';
+
+// Packaged assets (migrations/, kb-template/) + the migration runners.
+export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
+export {
+  runCoreMigrations,
+  runEnterpriseMigrations,
+} from './modules/database/migrate.js';
+export { getDb, type Database } from './modules/database/connection.js';
+
+// Build identity surfaced by GET /api/health.
+export { GIT_SHA, resolveGitSha } from './version.js';
+
+// Express `Request` augmentation carriers (userId/userEmail — auth.middleware;
+// token payloads — tool-auth + external-api-key interface). Re-exported by
+// VALUE/type so the `declare global` blocks land in this package's public
+// declaration graph.
+export { createAuthMiddleware, AUTH_COOKIE_NAME } from './modules/auth/auth.middleware.js';
+export {
+  createToolAuthMiddleware,
+  createManualAuthMiddleware,
+} from './modules/tool-auth/tool-auth.middleware.js';
+export type {
+  IExternalApiKeyService,
+  ExternalApiKeySummary,
+} from './modules/tool-auth/external-api-key.interface.js';
+
+// Key port/seam types an overlay implements.
+export type { ISessionSink } from './modules/workspace/session-sink.js';
+export type {
+  ISystemNoticeSink,
+  RecoveryAgentRunner,
+} from './modules/workflow/pending-commits.worker.js';
+export type { ILlmUsageMeter } from './modules/tool-auth/llm-usage-meter.js';
+export type { AuthProviderPlugin } from './modules/auth/auth.routes.js';
+export type { IErasureParticipant } from './modules/auth/account-erasure.service.js';
+export {
+  WorkflowHooks,
+  type CommitValidationHook,
+  type CommitValidationContext,
+  type PreWriteHook,
+  type PreWriteContext,
+} from './modules/workflow/workflow-hooks.js';

package/src/modules/access/__tests__/access-control.atref-batch.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
+
+const execFileAsync = promisify(execFile);
+const PROCESS_MAP_DIR = 'knowledge-base';
+
+/**
+ * `canWriteBatchAtRef` / the batched at-ref own-entries read — backed by ONE
+ * `git cat-file --batch` process whose length-prefixed output we parse by
+ * hand, so exercise it against a REAL git repo: found blobs, a path missing
+ * at the ref (the `<spec> missing` line), a path with spaces, and frontmatter
+ * deny resolution — all in one batch, order-aligned.
+ */
+describe('AccessControlService — at-ref batch reads (git cat-file --batch)', () => {
+  let root: string;
+  let repo: string;
+  let svc: AccessControlService;
+  const workspaceId = 'ws-atref-1';
+  const admin = 'razvan@bevel.software';
+
+  async function git(...args: string[]): Promise<void> {
+    await execFileAsync('git', ['-C', repo, ...args]);
+  }
+
+  beforeAll(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-atref-'));
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+    await fs.mkdir(path.join(repo, 'Knowledge'), { recursive: true });
+
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - razvan@bevel.software\n');
+    await fs.writeFile(path.join(repo, 'access.md'), '---\nwrite:\n  - Admin\n---\n');
+    await fs.writeFile(path.join(repo, 'Knowledge/plain.md'), '# plain\n');
+    await fs.writeFile(
+      path.join(repo, 'Knowledge/denied.md'),
+      '---\nwrite:\n  - deny razvan <razvan@bevel.software>\n---\n# denied\n',
+    );
+    await fs.writeFile(path.join(repo, 'Knowledge/with space.md'), '# spaced\n');
+
+    await execFileAsync('git', ['init', '-b', 'main', repo]);
+    await git('config', 'user.email', 'test@example.com');
+    await git('config', 'user.name', 'Test');
+    await git('add', '-A');
+    await git('commit', '-m', 'seed');
+
+    const stub = {
+      getWorkspacePath: async () => workspaceDir,
+      // Fixture repo has no remote; at-ref model loading fetches best-effort.
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    svc = new AccessControlService(stub, PROCESS_MAP_DIR);
+  });
+
+  afterAll(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('resolves a mixed batch in one pass: grants, frontmatter deny, spaces, and a missing path', async () => {
+    const paths = [
+      'Knowledge/plain.md', // dir-chain Admin grant → true
+      'Knowledge/denied.md', // own frontmatter deny → false
+      'Knowledge/with space.md', // found blob whose SPEC contains spaces → true
+      'Knowledge/not-there.md', // missing at the ref (`<spec> missing` line) → dir-chain verdict
+    ];
+    const map = await svc.canWriteBatchAtRef(workspaceId, 'main', admin, paths);
+    expect(map).not.toBeNull();
+    expect(map!.get('Knowledge/plain.md')).toBe(true);
+    expect(map!.get('Knowledge/denied.md')).toBe(false);
+    expect(map!.get('Knowledge/with space.md')).toBe(true);
+    expect(map!.get('Knowledge/not-there.md')).toBe(true);
+  });
+
+  it('matches the single-path at-ref resolution exactly', async () => {
+    // The batch is a pure performance change — verdicts must be identical to
+    // the per-path `git show` route the single-path helper still uses.
+    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/denied.md')).toBe(false);
+    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/plain.md')).toBe(true);
+  });
+
+  it('eligibleWritersForPathsAtRef honours the same batched own-entries', async () => {
+    const map = await svc.eligibleWritersForPathsAtRef(workspaceId, 'main', [
+      'Knowledge/plain.md',
+      'Knowledge/denied.md',
+    ]);
+    expect(map).not.toBeNull();
+    expect(map!.get('Knowledge/plain.md')!.roles).toContain('Admin');
+    // The per-user deny strips razvan from the expanded email set.
+    expect(map!.get('Knowledge/denied.md')!.emails.has(admin)).toBe(false);
+    expect(map!.get('Knowledge/plain.md')!.emails.has(admin)).toBe(true);
+  });
+});

package/src/modules/access/__tests__/access-control.read-batch.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
+
+const PROCESS_MAP_DIR = 'knowledge-base';
+
+async function writeFile(repo: string, rel: string, contents: string): Promise<void> {
+  const abs = path.join(repo, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, contents);
+}
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+const ROLES_YAML = `roles:
+  Admin:
+    - razvan@bevel.software
+  Product Manager:
+    - felix@example.com
+`;
+
+/**
+ * canReadBatch = the read check behind BOTH the content routes and the
+ * file-explorer tree. It must honour the FULL rule set — the folder
+ * `access.md` chain AND each node's own frontmatter — so a file the caller
+ * can't open never appears in the tree, and a frontmatter-only grant is
+ * discoverable. (This replaced the dir-chain-only `canReadBatchShallow`,
+ * whose frontmatter blindness let a frontmatter-denied file show in the
+ * sidebar and then 403 on open.)
+ */
+describe('AccessControlService.canReadBatch — tree/content parity', () => {
+  let root: string;
+  const workspaceId = 'ws-read-batch-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-read-batch-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function seed() {
+    const workspaceDir = path.join(root, workspaceId);
+    const repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+    await fs.mkdir(repo, { recursive: true });
+    await writeFile(repo, 'roles.yaml', ROLES_YAML);
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    // Folder-level read restriction (dir-chain rule). Product Manager = felix; ali has no role.
+    await writeFile(repo, 'Knowledge/Secret/access.md', '---\nread:\n  - Product Manager\n---\n');
+    await writeFile(repo, 'Knowledge/Secret/Foo.md', '# secret\n');
+    // Public folder via the built-in everyone role.
+    await writeFile(repo, 'Knowledge/Open/access.md', '---\nread:\n  - everyone\n---\n');
+    // Node restricted ONLY by its own frontmatter — the batch must see it.
+    await writeFile(
+      repo,
+      'Knowledge/Open/SelfRestricted.md',
+      '---\nread:\n  - deny everyone\n  - Product Manager\n---\n# self\n',
+    );
+    // Public via folder access.md.
+    await writeFile(repo, 'Knowledge/Open/Normal.md', '# normal\n');
+    // Node granted ONLY by its own frontmatter — the batch must discover it.
+    await writeFile(
+      repo,
+      'Knowledge/Closed/SelfGranted.md',
+      '---\nread:\n  - Product Manager\n---\n# self\n',
+    );
+    const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR);
+    return { svc, repo };
+  }
+
+  const ali = 'ali@bevel.software'; // not in any read: list, not admin
+  const felix = 'felix@example.com'; // listed
+
+  it('honours folder-level read rules (denies non-listed, allows listed)', async () => {
+    const { svc } = await seed();
+    const m = await svc.canReadBatch(workspaceId, ali, ['Knowledge/Secret/Foo.md']);
+    expect(m.get('Knowledge/Secret/Foo.md')).toBe(false);
+    const mf = await svc.canReadBatch(workspaceId, felix, ['Knowledge/Secret/Foo.md']);
+    expect(mf.get('Knowledge/Secret/Foo.md')).toBe(true);
+  });
+
+  it('honours a node-only frontmatter DENY (batch verdict matches the content route)', async () => {
+    const { svc } = await seed();
+    const p = 'Knowledge/Open/SelfRestricted.md';
+    // Full single-file canRead denies ali…
+    expect(await svc.canRead(workspaceId, ali, p)).toBe(false);
+    // …and the batch (tree) agrees, so the file never shows in the sidebar.
+    const batch = await svc.canReadBatch(workspaceId, ali, [p]);
+    expect(batch.get(p)).toBe(false);
+    // The frontmatter grant still lets felix through.
+    const felixBatch = await svc.canReadBatch(workspaceId, felix, [p]);
+    expect(felixBatch.get(p)).toBe(true);
+  });
+
+  it('discovers a node whose ONLY read grant is in node frontmatter', async () => {
+    const { svc } = await seed();
+    const p = 'Knowledge/Closed/SelfGranted.md';
+    expect(await svc.canRead(workspaceId, felix, p)).toBe(true);
+    const batch = await svc.canReadBatch(workspaceId, felix, [p]);
+    expect(batch.get(p)).toBe(true);
+  });
+
+  it('allows a public node via read: everyone', async () => {
+    const { svc } = await seed();
+    const m = await svc.canReadBatch(workspaceId, ali, ['Knowledge/Open/Normal.md']);
+    expect(m.get('Knowledge/Open/Normal.md')).toBe(true);
+  });
+
+  it('memoizes frontmatter reads per workspace and re-reads after invalidate()', async () => {
+    const { svc, repo } = await seed();
+    const p = 'Knowledge/Open/SelfRestricted.md';
+    // Warm the cache with the deny in place.
+    expect((await svc.canReadBatch(workspaceId, ali, [p])).get(p)).toBe(false);
+    // Remove the deny on disk. The memo may still serve the old verdict…
+    await writeFile(repo, p, '# self, unrestricted\n');
+    // …but after invalidate() (fired on every commit/pull/switch) the fresh
+    // frontmatter is read and the folder's `read: everyone` applies.
+    svc.invalidate(workspaceId);
+    expect((await svc.canReadBatch(workspaceId, ali, [p])).get(p)).toBe(true);
+  });
+});