@bevel-software/platform-core-backend 0.10.0 → 0.11.1

package/src/modules/access/__tests__/admin-locked-commit.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { AdminLockedCommits } from '../admin-locked-commit.js';
+import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../workflow/workflow.errors.js';
+import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
+
+const KB = 'knowledge-base';
+const BRANCH = 'main';
+const WS = 'ws-locked';
+const ACTOR: AuthUser = { id: 'u-1', email: 'admin@x.io', name: 'Admin' } as AuthUser;
+
+/**
+ * Lock-release semantics of `withFileLocks` (cubic P2: a releaseLock whose
+ * commit ENQUEUE fails after a successful batch commit stranded every held
+ * lock until TTL). Success path must release via releaseLockNoCommit (no
+ * enqueue involved); the push-retry path must keep releaseLock (the enqueued
+ * commit IS the retry); and a single failed release must not strand the rest.
+ */
+
+function makeHarness(opts: {
+  commitError?: Error;
+  releaseLockError?: Error;
+}) {
+  const files = new Map<string, string>();
+  const locks = new Map<string, AuthUser>();
+  const releaseLockCalls: string[] = [];
+  const releaseNoCommitCalls: string[] = [];
+
+  const workspaceService = {
+    getWorkspacePath: async () => '/tmp/nowhere',
+    readFile: async (_id: string, wsRel: string) => {
+      const v = files.get(wsRel);
+      if (v === undefined) {
+        const err = new Error(`ENOENT ${wsRel}`) as NodeJS.ErrnoException;
+        err.code = 'ENOENT';
+        throw err;
+      }
+      return v;
+    },
+    writeFile: async (_id: string, wsRel: string, content: string) => void files.set(wsRel, content),
+    deleteFile: async (_id: string, wsRel: string) => void files.delete(wsRel),
+  } as unknown as IWorkspaceService;
+
+  const workflowService = {
+    acquireLock: vi.fn(async (_w: string, _b: string, p: string, user: AuthUser) => {
+      if (locks.has(p)) return { acquired: false, lock: { holderUserId: 'x', holderName: 'X' } };
+      locks.set(p, user);
+      return { acquired: true, lock: { holderUserId: user.id, holderName: user.name } };
+    }),
+    releaseLock: vi.fn(async (_w: string, _b: string, p: string) => {
+      releaseLockCalls.push(p);
+      if (opts.releaseLockError) throw opts.releaseLockError; // enqueue failed → row NOT dropped
+      locks.delete(p);
+    }),
+    releaseLockNoCommit: vi.fn(async (_w: string, _b: string, p: string) => {
+      releaseNoCommitCalls.push(p);
+      locks.delete(p);
+    }),
+    commitChanges: vi.fn(async () => {
+      if (opts.commitError) throw opts.commitError;
+      return {};
+    }),
+  } as unknown as IWorkflowService;
+
+  const locked = new AdminLockedCommits({
+    workspaceService,
+    workflowService,
+    kbDirName: KB,
+    defaultBranchOf: () => BRANCH,
+    makeError: (message, status, payload) => new WorkflowDomainError(message, status, payload),
+    logTag: 'test-admin',
+    contendedSubject: 'Things',
+  });
+
+  return { locked, locks, files, releaseLockCalls, releaseNoCommitCalls };
+}
+
+describe('AdminLockedCommits.withFileLocks — release semantics', () => {
+  it('SUCCESS: batch-committed paths release via releaseLockNoCommit — a broken enqueue cannot strand them', async () => {
+    // releaseLock models "the pending-commit ENQUEUE fails": it throws and the
+    // lock row stays held. If the success path still used it, both locks would
+    // strand until TTL. With the fix they must all be free afterwards.
+    const h = makeHarness({ releaseLockError: new Error('enqueue exploded: sqlite disk I/O error') });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      await h.locked.withFileLocks(WS, ACTOR, ['groups.yaml', 'roles.yaml'], async () => {
+        await h.locked.writeAndCommitLocked(
+          WS,
+          ACTOR,
+          [
+            { repoRel: 'groups.yaml', content: 'groups: {}\n', original: null },
+            { repoRel: 'roles.yaml', content: 'roles: {}\n', original: 'roles:\n' },
+          ],
+          'test commit',
+        );
+      });
+      expect(h.locks.size).toBe(0); // ZERO held locks
+      expect(h.releaseNoCommitCalls.sort()).toEqual([`${KB}/groups.yaml`, `${KB}/roles.yaml`]);
+      expect(h.releaseLockCalls).toEqual([]); // the queue was never touched
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('POST-COMMIT FAILURE: fn throwing after the batch landed still releases committed paths without the queue', async () => {
+    // The commit+push succeeded; a later step inside fn (roster read, event
+    // emission) blew up. The failure says nothing about the tree — the
+    // committed paths are clean, and enqueueing a release commit for them
+    // risks stranding a known-clean lock on a broken queue.
+    const h = makeHarness({ releaseLockError: new Error('enqueue exploded') });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      await expect(
+        h.locked.withFileLocks(WS, ACTOR, ['groups.yaml', 'roles.yaml'], async () => {
+          await h.locked.writeAndCommitLocked(
+            WS,
+            ACTOR,
+            [
+              { repoRel: 'groups.yaml', content: 'groups: {}\n', original: null },
+              { repoRel: 'roles.yaml', content: 'roles: {}\n', original: 'roles:\n' },
+            ],
+            'test commit',
+          );
+          throw new Error('post-commit boom');
+        }),
+      ).rejects.toThrow(/post-commit boom/);
+      expect(h.locks.size).toBe(0); // ZERO held locks
+      expect(h.releaseNoCommitCalls.sort()).toEqual([`${KB}/groups.yaml`, `${KB}/roles.yaml`]);
+      expect(h.releaseLockCalls).toEqual([]); // the queue was never touched
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('SUCCESS: a held path the batch never committed keeps commit-on-release (releaseLock)', async () => {
+    // A prior holder's queued work could still be dirty on such a path — a
+    // discard would destroy it, so the untouched lock releases the old way.
+    const h = makeHarness({});
+    await h.locked.withFileLocks(WS, ACTOR, ['groups.yaml', 'roles.yaml'], async () => {
+      await h.locked.writeAndCommitLocked(
+        WS,
+        ACTOR,
+        [{ repoRel: 'roles.yaml', content: 'roles: {}\n', original: 'roles:\n' }],
+        'test commit',
+      );
+    });
+    expect(h.locks.size).toBe(0);
+    expect(h.releaseNoCommitCalls).toEqual([`${KB}/roles.yaml`]);
+    expect(h.releaseLockCalls).toEqual([`${KB}/groups.yaml`]);
+  });
+
+  it('PUSH-RETRY: PushNeedsAgentResolutionError keeps releaseLock (the enqueued commit retries the push)', async () => {
+    const h = makeHarness({
+      commitError: new PushNeedsAgentResolutionError(BRANCH, `${KB}/roles.yaml`, 'push refused', 'no retry'),
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      await expect(
+        h.locked.withFileLocks(WS, ACTOR, ['roles.yaml'], async () => {
+          await h.locked.writeAndCommitLocked(
+            WS,
+            ACTOR,
+            [{ repoRel: 'roles.yaml', content: 'roles: {}\n', original: 'roles:\n' }],
+            'test commit',
+          );
+        }),
+      ).rejects.toBeInstanceOf(PushNeedsAgentResolutionError);
+      expect(h.releaseLockCalls).toEqual([`${KB}/roles.yaml`]); // releaseLock, NOT noCommit
+      expect(h.releaseNoCommitCalls).toEqual([]);
+      expect(h.locks.size).toBe(0);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('PUSH-RETRY: one failed release logs and continues — the REST of the locks are still released', async () => {
+    const h = makeHarness({
+      commitError: new PushNeedsAgentResolutionError(BRANCH, `${KB}/roles.yaml`, 'push refused', 'no retry'),
+      releaseLockError: new Error('enqueue exploded'),
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      await expect(
+        h.locked.withFileLocks(WS, ACTOR, ['a.yaml', 'b.yaml'], async () => {
+          await h.locked.writeAndCommitLocked(
+            WS,
+            ACTOR,
+            [
+              { repoRel: 'a.yaml', content: 'a\n', original: null },
+              { repoRel: 'b.yaml', content: 'b\n', original: null },
+            ],
+            'test commit',
+          );
+        }),
+      ).rejects.toBeInstanceOf(PushNeedsAgentResolutionError);
+      // BOTH releases were attempted despite the first one throwing.
+      expect(h.releaseLockCalls.sort()).toEqual([`${KB}/a.yaml`, `${KB}/b.yaml`]);
+      expect(warn).toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('FAILURE with restore: commit-on-release is kept (restored bytes are clean; queued work preserved)', async () => {
+    const h = makeHarness({ commitError: new Error('commit exploded') });
+    await expect(
+      h.locked.withFileLocks(WS, ACTOR, ['roles.yaml'], async () => {
+        await h.locked.writeAndCommitLocked(
+          WS,
+          ACTOR,
+          [{ repoRel: 'roles.yaml', content: 'roles: {}\n', original: 'roles:\n' }],
+          'test commit',
+        );
+      }),
+    ).rejects.toThrow('commit exploded');
+    expect(h.releaseLockCalls).toEqual([`${KB}/roles.yaml`]);
+    expect(h.releaseNoCommitCalls).toEqual([]);
+    expect(h.locks.size).toBe(0);
+    expect(h.files.get(`${KB}/roles.yaml`)).toBe('roles:\n'); // restored
+  });
+});

package/src/modules/access/__tests__/admin-route-helpers.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+import { toHttpError, requireNonEmptyString } from '../admin-route-helpers.js';
+import { WorkflowDomainError } from '../../workflow/workflow.errors.js';
+import { AccessMutationError } from '../access-mutation.service.js';
+
+describe('toHttpError — the shared access-family error shape', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('a sub-500 domain error keeps its status, message, and payload', () => {
+    const err = new WorkflowDomainError('groups are being edited', 409, { kind: 'idp-mode' });
+    expect(toHttpError(err, 'test')).toEqual({
+      status: 409,
+      body: { error: 'groups are being edited', kind: 'idp-mode' },
+    });
+  });
+
+  it('a 500-status DOMAIN error never leaks its message — generic body, full server-side log', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    // AccessMutationService wraps unexpected raw errors (fs/db failures) in a
+    // 500 AccessMutationError with the RAW message — that must not reach the
+    // client.
+    const err = new AccessMutationError("ENOENT: open '/srv/kb/secret-folder/access.md'", 500);
+    const { status, body } = toHttpError(err, 'test');
+    expect(status).toBe(500);
+    expect(body).toEqual({ error: 'Internal error.' });
+    expect(JSON.stringify(body)).not.toContain('secret-folder');
+    expect(spy).toHaveBeenCalled(); // the details land server-side
+  });
+
+  it('a raw (non-domain) error is a generic 500', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    expect(toHttpError(new Error('db connection string postgres://u:p@host'), 'test')).toEqual({
+      status: 500,
+      body: { error: 'Internal error.' },
+    });
+  });
+
+  it("a payload key named 'error' cannot overwrite the client-facing message", () => {
+    const err = new WorkflowDomainError('the real message', 422, { error: 'spoofed', kind: 'x' });
+    const { body } = toHttpError(err, 'test');
+    expect(body.error).toBe('the real message');
+    expect(body.kind).toBe('x');
+  });
+});
+
+describe('requireNonEmptyString', () => {
+  it('accepts a plain string and rejects non-strings with a 400 domain error', () => {
+    expect(requireNonEmptyString('ok', 'field')).toBe('ok');
+    for (const bad of [42, null, undefined, ['a'], { a: 1 }, '   ']) {
+      let caught: unknown;
+      try {
+        requireNonEmptyString(bad, 'field');
+      } catch (err) {
+        caught = err;
+      }
+      expect(caught).toBeInstanceOf(WorkflowDomainError);
+      expect((caught as WorkflowDomainError).status).toBe(400);
+    }
+  });
+});

package/src/modules/access/__tests__/directory-sync-bot.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+
+import type { Database } from '../../database/connection.js';
+import {
+  DIRECTORY_SYNC_BOT_EMAIL,
+  DIRECTORY_SYNC_BOT_NAME,
+  ensureDirectorySyncBot,
+} from '../directory-sync-bot.js';
+
+interface Row {
+  id: string;
+  email: string;
+  name: string;
+  avatarUrl: string | null;
+  passwordHash: string | null;
+}
+
+/** Minimal fake of the two drizzle chains `ensureDirectorySyncBot` runs. */
+function fakeDb(opts: { existing: Row | null }): Database {
+  const created: Row = {
+    id: 'bot-row',
+    email: DIRECTORY_SYNC_BOT_EMAIL,
+    name: DIRECTORY_SYNC_BOT_NAME,
+    avatarUrl: null,
+    passwordHash: null,
+  };
+  return {
+    insert: () => ({
+      values: () => ({
+        onConflictDoNothing: () => ({
+          // Conflict (row exists) → empty; otherwise the fresh bot row.
+          returning: async () => (opts.existing ? [] : [created]),
+        }),
+      }),
+    }),
+    select: () => ({
+      from: () => ({
+        where: () => ({
+          limit: async () => (opts.existing ? [opts.existing] : []),
+        }),
+      }),
+    }),
+  } as unknown as Database;
+}
+
+describe('ensureDirectorySyncBot — the bot identity is exclusive', () => {
+  it('creates the bot row when the email is free', async () => {
+    const bot = await ensureDirectorySyncBot(fakeDb({ existing: null }));
+    expect(bot).toMatchObject({ email: DIRECTORY_SYNC_BOT_EMAIL, name: DIRECTORY_SYNC_BOT_NAME });
+  });
+
+  it('reuses an existing row only when it IS the bot', async () => {
+    const bot = await ensureDirectorySyncBot(
+      fakeDb({
+        existing: {
+          id: 'prev-bot',
+          email: DIRECTORY_SYNC_BOT_EMAIL,
+          name: DIRECTORY_SYNC_BOT_NAME,
+          avatarUrl: null,
+          passwordHash: null,
+        },
+      }),
+    );
+    expect(bot.id).toBe('prev-bot');
+  });
+
+  it('REFUSES to bind the materializer to a pre-existing human account under the bot email', async () => {
+    // The machine-owned write rule on synced-groups.yaml authorizes by this
+    // email alone — silently adopting a human's row would attribute every
+    // sync commit to them and hand their session the bot's write authority.
+    await expect(
+      ensureDirectorySyncBot(
+        fakeDb({
+          existing: {
+            id: 'human-1',
+            email: DIRECTORY_SYNC_BOT_EMAIL,
+            name: 'Mallory Human',
+            avatarUrl: null,
+            passwordHash: null,
+          },
+        }),
+      ),
+    ).rejects.toThrow(/already belongs to an existing account/);
+  });
+
+  it('REFUSES a password-capable row even when it mimics the bot display name', async () => {
+    // A display name is not an identity marker — anyone can carry the bot's
+    // name. A password hash IS hard evidence: the bot never signs in and is
+    // never provisioned credentials, so a login-capable row under the bot
+    // email is a person's account (or a credential a person could use) and
+    // must never be adopted as the materializer's identity.
+    await expect(
+      ensureDirectorySyncBot(
+        fakeDb({
+          existing: {
+            id: 'human-2',
+            email: DIRECTORY_SYNC_BOT_EMAIL,
+            name: DIRECTORY_SYNC_BOT_NAME,
+            avatarUrl: null,
+            passwordHash: 'scrypt:deadbeef',
+          },
+        }),
+      ),
+    ).rejects.toThrow(/can sign in with a password/);
+  });
+});

package/src/modules/access/__tests__/grant-sources.test.ts

@@ -202,3 +202,70 @@ describe('AccessControlService.grantSources', () => {
     expect(src.download).toEqual([{ kind: 'direct' }]);
   });
 });
+
+describe('grantSources — principal kind under group shadowing', () => {
+  let root: string;
+  let repo: string;
+  let svc: AccessControlService;
+  const workspaceId = 'ws-gs-shadow';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+    await fs.mkdir(repo, { recursive: true });
+    await writeFile(repo, 'roles.yaml', ROLES_YAML);
+    // A GROUP named Engineer shadows the Engineer ROLE: the bare token is the
+    // group's, `role/engineer` is the role's.
+    await writeFile(repo, 'groups.yaml', 'groups:\n  Engineer:\n    - pat@x.io\n');
+    svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR);
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("a shadowed BARE grant belongs to the GROUP — it must not hide the role's ancestor grant", async () => {
+    // The cubic case: bare (group) grant on the target, role/ grant on the
+    // ancestor. Attributing the bare token to the role would report the role
+    // as `direct` here — hiding the real role/<Name> ancestor grant and
+    // making its revoke a false no-op.
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - role/Engineer\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');
+
+    const roleSrc = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
+      kind: 'role',
+      role: 'role/Engineer',
+    });
+    // The ROLE's only entry is the ancestor role/ grant.
+    expect(roleSrc.write).toEqual([{ kind: 'ancestor', path: 'access.md' }]);
+
+    const groupSrc = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
+      kind: 'role',
+      role: 'Engineer', // bare = whoever owns the bare key = the group
+    });
+    // The GROUP's only entry is the direct bare grant.
+    expect(groupSrc.write).toEqual([{ kind: 'direct' }]);
+  });
+
+  it("a shadowed role/ grant is never attributed to the GROUP principal", async () => {
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - role/Engineer\n---\n');
+    const groupSrc = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
+      kind: 'role',
+      role: 'Engineer',
+    });
+    expect(groupSrc).toEqual({}); // the group holds nothing here
+  });
+
+  it('UNSHADOWED both spellings still count as the role (legacy bare grants stay removable)', async () => {
+    await fs.rm(path.join(repo, 'groups.yaml'));
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - role/Engineer\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
+      kind: 'role',
+      role: 'Engineer',
+    });
+    expect(src.write).toEqual([{ kind: 'direct' }, { kind: 'ancestor', path: 'access.md' }]);
+  });
+});