platform/src/servers/permissions/authorize.test.ts

import { describe, expect, test } from 'bun:test';
import type { UserRole } from 'officerdb';
import type { EffectivePermissions } from './authorize';
import { decideApiRequest, decideWsProvider, resolveEffectivePermissions } from './authorize';
import type { PermissionLevel } from './registry';
import { CORE_PERMISSIONS } from './registry';

/*
  The resolver, which its own header calls the file standing between a Member and a shell — and which had no
  automated tests at all until 2026-08-22.

  It had none because every path needed two database calls. The decisions are now split from the fetching
  (`resolveEffectivePermissions`, `decideApiRequest`, `decideWsProvider` are pure), so this file needs no
  mock, no database and no `officerdb` stub — which matters beyond convenience: the one file in this
  repository that mocks `officerdb` leaks its stub into whatever runs after it.

  REAL registry keys throughout, deliberately. A suite built on invented permissions would keep passing
  after a rename, which is the failure mode a test of an authorization table can least afford. If a key here
  disappears, this file should go red.
*/

const member = (osUser: string | null = 'm1'): { role: UserRole; osUser: string | null } => ({
  role: 'Member',
  osUser,
});
const grants = (...pairs: Array<[string, PermissionLevel]>) => new Map<string, PermissionLevel>(pairs);
const resolve = (user: { role: UserRole; osUser: string | null }, g = grants()) => resolveEffectivePermissions(user, g);

/** No account at all — an unauthenticated or deleted caller, as the async wrapper reports it. */
const NOBODY: EffectivePermissions = { isOwner: false, grants: new Map() };

describe('resolving what an account holds', () => {
  test('the owner bypasses, and carries no grants to consult', () => {
    const owner = resolve({ role: 'Super Admin', osUser: null });
    expect(owner.isOwner).toBe(true);
    // Empty on purpose: an owner's grants are never read, and filling them would invite somebody to.
    expect(owner.grants.size).toBe(0);
  });

  test('a member gets every core permission at write, granted nothing', () => {
    const held = resolve(member()).grants;
    for (const permission of CORE_PERMISSIONS) expect(held.get(permission.key)).toBe('write');
  });

  test('core is write even though nothing granted it', () => {
    // A read-only "change your own password" is not a coherent thing to offer, which is why core is not
    // levelled. Pinned because a future levels-everywhere refactor would silently break it.
    expect(resolve(member()).grants.get('account')).toBe('write');
  });

  test('an app grant is honoured at the level given', () => {
    expect(resolve(member(), grants(['calendar', 'read'])).grants.get('calendar')).toBe('read');
    expect(resolve(member(), grants(['calendar', 'write'])).grants.get('calendar')).toBe('write');
  });

  // The rule that only exists because getOwnerHomeDir ignores its argument: a confined grant with no Linux
  // user to confine to would resolve to the OWNER's home.
  test('a confined grant needs a Linux account', () => {
    expect(resolve(member('m1'), grants(['files', 'write'])).grants.get('files')).toBe('write');
    expect(resolve(member(null), grants(['files', 'write'])).grants.has('files')).toBe(false);
  });

  test('every confined permission is dropped together, not one by one', () => {
    const held = resolve(member(null), grants(['files', 'write'], ['terminal', 'write'], ['chat', 'write']));
    for (const key of ['files', 'terminal', 'chat']) expect(held.grants.has(key)).toBe(false);
  });

  // The database has no CHECK stopping these rows; the API refuses to write one. This is the layer that
  // has to hold if one ever exists.
  test('an execution grant in the table is ignored', () => {
    expect(resolve(member(), grants(['tasks', 'write'])).grants.has('tasks')).toBe(false);
  });

  test('an admin grant in the table is ignored', () => {
    expect(resolve(member(), grants(['user-admin', 'write'])).grants.has('user-admin')).toBe(false);
    expect(resolve(member(), grants(['server-admin', 'write'])).grants.has('server-admin')).toBe(false);
  });

  test('a grant naming a permission that no longer exists is ignored', () => {
    const held = resolve(member(), grants(['cliamp', 'write'], ['a-plugin-uninstalled-last-year', 'read']));
    expect(held.grants.has('cliamp')).toBe(false);
    expect(held.grants.has('a-plugin-uninstalled-last-year')).toBe(false);
    // …and does not disturb what is legitimately held.
    expect(held.grants.get('account')).toBe('write');
  });
});

describe('deciding an HTTP request', () => {
  const owner: EffectivePermissions = { isOwner: true, grants: new Map() };

  test('the owner is allowed anything, including paths nothing serves', () => {
    expect(decideApiRequest(owner, 'DELETE', '/api/users/9').allowed).toBe(true);
    expect(decideApiRequest(owner, 'GET', '/api/nothing-serves-this').allowed).toBe(true);
  });

  test('a path no permission covers is refused, not allowed by default', () => {
    const d = decideApiRequest(NOBODY, 'GET', '/api/nothing-serves-this');
    expect(d.allowed).toBe(false);
    expect(d.reason).toContain('no permission covers this path');
  });

  test('an execution permission is refused however it is granted', () => {
    // Refused by KIND, before any grant lookup — so a row granting it changes nothing.
    const forged = resolve(member(), grants(['tasks', 'write']));
    const d = decideApiRequest(forged, 'GET', '/api/tasks');
    expect(d.allowed).toBe(false);
    expect(d.reason).toContain('runs as the server owner');
  });

  test('an admin permission is refused', () => {
    const d = decideApiRequest(resolve(member()), 'GET', '/api/users');
    expect(d.allowed).toBe(false);
    expect(d.reason).toContain('restricted to the server owner');
  });

  // The one self-service route in the registry: updating your own profile lives on the router that also
  // holds account administration.
  test('a self-service route is allowed with no grant at all', () => {
    expect(decideApiRequest(resolve(member()), 'PUT', '/api/users').allowed).toBe(true);
  });

  test('self-service is exact — neither the method nor the path may drift', () => {
    expect(decideApiRequest(resolve(member()), 'POST', '/api/users').allowed).toBe(false);
    expect(decideApiRequest(resolve(member()), 'PUT', '/api/users/7').allowed).toBe(false);
  });

  test('no grant means no access, with the permission named', () => {
    const d = decideApiRequest(resolve(member()), 'GET', '/api/file-browser');
    expect(d.allowed).toBe(false);
    expect(d.reason).toContain('your role does not have access to');
  });

  test('read grants reads and refuses writes', () => {
    const held = resolve(member('m1'), grants(['files', 'read']));
    expect(decideApiRequest(held, 'GET', '/api/file-browser').allowed).toBe(true);
    const write = decideApiRequest(held, 'POST', '/api/file-browser');
    expect(write.allowed).toBe(false);
    expect(write.reason).toContain('read-only');
  });

  test('write grants both', () => {
    const held = resolve(member('m1'), grants(['files', 'write']));
    expect(decideApiRequest(held, 'GET', '/api/file-browser').allowed).toBe(true);
    expect(decideApiRequest(held, 'POST', '/api/file-browser').allowed).toBe(true);
  });

  // A read that has to be a POST — the body is too big for a query string — must not need write.
  //
  // The path is `/api/file-browser/download`, not `/api/download`: readOnlyWrites entries are RELATIVE to
  // the permission's own api prefix. Worth a comment because the absolute form looks right, is what I wrote
  // first, and fails as "no permission covers this path" rather than as a level problem — a misleading
  // error for a misleading path.
  test('a readOnlyWrites path is allowed at read level', () => {
    const held = resolve(member('m1'), grants(['files', 'read']));
    expect(decideApiRequest(held, 'POST', '/api/file-browser/download').allowed).toBe(true);
    // And the same POST elsewhere under the prefix still needs write.
    expect(decideApiRequest(held, 'POST', '/api/file-browser/move').allowed).toBe(false);
  });

  // The two rules composing: granted, but with no kernel boundary to be granted inside.
  test('a granted confined permission is still refused without a Linux account', () => {
    const held = resolve(member(null), grants(['files', 'write']));
    expect(decideApiRequest(held, 'GET', '/api/file-browser').allowed).toBe(false);
  });

  test('an unauthenticated caller is refused everything', () => {
    for (const path of ['/api/file-browser', '/api/chat', '/api/users', '/api/tasks']) {
      expect(decideApiRequest(NOBODY, 'GET', path).allowed).toBe(false);
    }
  });
});

describe('deciding a websocket', () => {
  test('the owner opens anything', () => {
    expect(decideWsProvider({ isOwner: true, grants: new Map() }, 'terminal')).toBe(true);
  });

  test('a provider no permission claims is refused', () => {
    expect(decideWsProvider(resolve(member()), 'not-a-provider')).toBe(false);
  });

  test('a confined socket needs the grant AND the Linux account', () => {
    expect(decideWsProvider(resolve(member('m1'), grants(['terminal', 'read'])), 'terminal')).toBe(true);
    expect(decideWsProvider(resolve(member(null), grants(['terminal', 'read'])), 'terminal')).toBe(false);
  });

  // No method to reason about, so any level opens it. Pinned because "read-only socket" is a tempting idea
  // that would silently close terminals granted at read.
  test('read is enough — a socket has no method', () => {
    expect(decideWsProvider(resolve(member('m1'), grants(['chat', 'read'])), 'chat')).toBe(true);
    expect(decideWsProvider(resolve(member('m1'), grants(['chat', 'read'])), 'chat-notify')).toBe(true);
  });

  test("an execution permission's socket is refused however it is granted", () => {
    const forged = resolve(member('m1'), grants(['tasks', 'write']));
    expect(decideWsProvider(forged, 'task-runner')).toBe(false);
    expect(decideWsProvider(forged, 'pipeline')).toBe(false);
  });

  test('an unauthenticated caller opens nothing', () => {
    for (const p of ['terminal', 'chat', 'task-runner', 'sidecar']) expect(decideWsProvider(NOBODY, p)).toBe(false);
  });
});

/*
  NOT covered here, and stated rather than left as a gap somebody has to notice:

  - `isOwnerOnlyRoute`. No permission in the registry declares `ownerOnly` yet — the field was added on
    2026-08-21 for plugin settings routes and has no user. It is checked before self-service and before
    kind, which is the part worth a test, and it cannot get one until a real permission uses it. Covering it
    with an invented permission would test this file's fixtures rather than the registry.
  - The grant cache and `invalidateRoleGrants`. They live on the async side, around a database call, which
    is exactly the half this split moved away from. Their contract — the one writer in
    `api/users/permissions-routes.ts` calls the invalidator — is a claim about call sites, not about logic,
    and a test here could only re-state it.
*/