Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.0 KB
Raw Blame
import { test, expect, describe } from 'bun:test';
import {
  hasScope,
  isScope,
  ALLOWED_SCOPES,
  ALLOWED_SCOPES_LIST,
  DCR_REGISTRABLE_SCOPES,
  dcrScopeViolation,
  scopesSupportedForDiscovery,
  assertAllowedScopes,
  filterAllowedScopes,
  InvalidScopeError,
  parseScopeString,
  type Scope,
} from '../src/core/scope.ts';

// ---------------------------------------------------------------------------
// Hierarchy table — admin → all, write → read, sibling non-implication
// ---------------------------------------------------------------------------

describe('hasScope — admin implies all (escape hatch)', () => {
  const all: Scope[] = ['read', 'write', 'admin', 'sources_admin', 'users_admin'];
  for (const required of all) {
    test(`admin → ${required}`, () => {
      expect(hasScope(['admin'], required)).toBe(true);
    });
  }
});

describe('hasScope — write implies read but not admin variants', () => {
  test('write → read', () => {
    expect(hasScope(['write'], 'read')).toBe(true);
  });
  test('write → write', () => {
    expect(hasScope(['write'], 'write')).toBe(true);
  });
  test('write does NOT imply admin', () => {
    expect(hasScope(['write'], 'admin')).toBe(false);
  });
  test('write does NOT imply sources_admin', () => {
    expect(hasScope(['write'], 'sources_admin')).toBe(false);
  });
  test('write does NOT imply users_admin', () => {
    expect(hasScope(['write'], 'users_admin')).toBe(false);
  });
});

describe('hasScope — sibling non-implication for *_admin scopes', () => {
  test('sources_admin → sources_admin only', () => {
    expect(hasScope(['sources_admin'], 'sources_admin')).toBe(true);
    expect(hasScope(['sources_admin'], 'users_admin')).toBe(false);
    expect(hasScope(['sources_admin'], 'write')).toBe(false);
    expect(hasScope(['sources_admin'], 'read')).toBe(false);
    expect(hasScope(['sources_admin'], 'admin')).toBe(false);
  });
  test('users_admin → users_admin only', () => {
    expect(hasScope(['users_admin'], 'users_admin')).toBe(true);
    expect(hasScope(['users_admin'], 'sources_admin')).toBe(false);
    expect(hasScope(['users_admin'], 'write')).toBe(false);
    expect(hasScope(['users_admin'], 'read')).toBe(false);
  });
});

describe('hasScope — read scope', () => {
  test('read → read', () => {
    expect(hasScope(['read'], 'read')).toBe(true);
  });
  test('read does NOT imply write', () => {
    expect(hasScope(['read'], 'write')).toBe(false);
  });
});

describe('hasScope — empty + unknown granted', () => {
  test('empty granted set returns false', () => {
    expect(hasScope([], 'read')).toBe(false);
  });
  test('unknown scope strings ignored gracefully (forward-compat)', () => {
    expect(hasScope(['flying-unicorn'], 'read')).toBe(false);
    expect(hasScope(['flying-unicorn', 'admin'], 'read')).toBe(true); // admin still implies
  });
});

describe('hasScope — multi-grant', () => {
  test('read + sources_admin combo', () => {
    expect(hasScope(['read', 'sources_admin'], 'read')).toBe(true);
    expect(hasScope(['read', 'sources_admin'], 'sources_admin')).toBe(true);
    expect(hasScope(['read', 'sources_admin'], 'write')).toBe(false);
  });
  test('write + sources_admin combo (gstack /setup-gbrain Path 4 token)', () => {
    expect(hasScope(['write', 'sources_admin'], 'read')).toBe(true);
    expect(hasScope(['write', 'sources_admin'], 'write')).toBe(true);
    expect(hasScope(['write', 'sources_admin'], 'sources_admin')).toBe(true);
    expect(hasScope(['write', 'sources_admin'], 'users_admin')).toBe(false);
  });
});

// ---------------------------------------------------------------------------
// F3 invariant: refresh-token requested-subset enforcement uses hasScope.
// Prove the v0.26.9-correct semantics (admin grant CAN refresh down to a
// subset; non-implied scope refresh fails).
// ---------------------------------------------------------------------------

describe('F3 refresh-token subset semantics under hasScope', () => {
  test('admin grant → refresh requesting sources_admin succeeds', () => {
    const granted = ['admin'];
    const requested = ['sources_admin'];
    expect(requested.every(s => hasScope(granted, s))).toBe(true);
  });
  test('admin grant → refresh requesting subset (read+write) succeeds', () => {
    const granted = ['admin'];
    const requested = ['read', 'write'];
    expect(requested.every(s => hasScope(granted, s))).toBe(true);
  });
  test('write grant → refresh requesting admin fails', () => {
    const granted = ['write'];
    const requested = ['admin'];
    expect(requested.every(s => hasScope(granted, s))).toBe(false);
  });
  test('write grant → refresh requesting sources_admin fails', () => {
    const granted = ['write'];
    const requested = ['sources_admin'];
    expect(requested.every(s => hasScope(granted, s))).toBe(false);
  });
  test('sources_admin grant → refresh requesting users_admin fails (sibling axis)', () => {
    const granted = ['sources_admin'];
    const requested = ['users_admin'];
    expect(requested.every(s => hasScope(granted, s))).toBe(false);
  });
});

// ---------------------------------------------------------------------------
// ALLOWED_SCOPES allowlist (D4) — registration-time gate
// ---------------------------------------------------------------------------

describe('ALLOWED_SCOPES — exact list pinned', () => {
  test('contains the 6 canonical scopes (v0.38: agent added)', () => {
    expect(ALLOWED_SCOPES.size).toBe(10);
    expect(ALLOWED_SCOPES.has('read')).toBe(true);
    expect(ALLOWED_SCOPES.has('write')).toBe(true);
    expect(ALLOWED_SCOPES.has('admin')).toBe(true);
    expect(ALLOWED_SCOPES.has('sources_admin')).toBe(true);
    expect(ALLOWED_SCOPES.has('users_admin')).toBe(true);
    expect(ALLOWED_SCOPES.has('agent')).toBe(true);
    expect(ALLOWED_SCOPES.has('skill_editor')).toBe(true);
    expect(ALLOWED_SCOPES.has('skill_publisher')).toBe(true);
    expect(ALLOWED_SCOPES.has('skills_member_self')).toBe(true);
    expect(ALLOWED_SCOPES.has('memory_confirm')).toBe(true);
  });
  test('list is sorted alphabetically (deterministic for wire/drift check)', () => {
    expect([...ALLOWED_SCOPES_LIST]).toEqual([
      'admin',
      'agent',
      'memory_confirm',
      'read',
      'skill_editor',
      'skill_publisher',
      'skills_member_self',
      'sources_admin',
      'users_admin',
      'write',
    ]);
  });
});

describe('isScope', () => {
  test('accepts allowed strings', () => {
    expect(isScope('read')).toBe(true);
    expect(isScope('sources_admin')).toBe(true);
  });
  test('rejects unknown strings', () => {
    expect(isScope('flying-unicorn')).toBe(false);
    expect(isScope('')).toBe(false);
    expect(isScope('READ')).toBe(false); // case-sensitive
  });
});

describe('assertAllowedScopes', () => {
  test('passes for valid set', () => {
    expect(() => assertAllowedScopes(['read', 'sources_admin'])).not.toThrow();
  });
  test('passes for empty', () => {
    expect(() => assertAllowedScopes([])).not.toThrow();
  });
  test('throws InvalidScopeError naming the bad scope', () => {
    try {
      assertAllowedScopes(['read', 'flying-unicorn']);
      throw new Error('expected throw');
    } catch (e) {
      expect(e).toBeInstanceOf(InvalidScopeError);
      expect((e as InvalidScopeError).invalidScope).toBe('flying-unicorn');
      expect((e as InvalidScopeError).message).toMatch(/flying-unicorn/);
      expect((e as InvalidScopeError).message).toMatch(/Allowed:/);
    }
  });
  test('throws on first invalid scope (short-circuits)', () => {
    try {
      assertAllowedScopes(['flying-unicorn', 'also-bad']);
      throw new Error('expected throw');
    } catch (e) {
      expect((e as InvalidScopeError).invalidScope).toBe('flying-unicorn');
    }
  });
});

describe('filterAllowedScopes', () => {
  test('keeps allowed and reports dropped unknowns', () => {
    const { allowed, dropped } = filterAllowedScopes([
      'read', 'offline_access', 'write', 'openid', 'read',
    ]);
    expect(allowed).toEqual(['read', 'write']);
    expect(dropped).toEqual(['offline_access', 'openid']);
  });
  test('all-unknown yields empty allowed', () => {
    const { allowed, dropped } = filterAllowedScopes(['openid', 'offline_access']);
    expect(allowed).toEqual([]);
    expect(dropped).toEqual(['openid', 'offline_access']);
  });
  test('empty input yields empty both', () => {
    expect(filterAllowedScopes([])).toEqual({ allowed: [], dropped: [] });
  });
});

describe('parseScopeString', () => {
  test('splits space-separated', () => {
    expect(parseScopeString('read write admin')).toEqual(['read', 'write', 'admin']);
  });
  test('drops empty fragments', () => {
    expect(parseScopeString('read  write')).toEqual(['read', 'write']);
  });
  test('handles undefined/null/empty', () => {
    expect(parseScopeString(undefined)).toEqual([]);
    expect(parseScopeString(null)).toEqual([]);
    expect(parseScopeString('')).toEqual([]);
  });
  test('does NOT validate (separation of concerns)', () => {
    expect(parseScopeString('read flying-unicorn')).toEqual(['read', 'flying-unicorn']);
  });
});

// ---------------------------------------------------------------------------
// scopesSupportedForDiscovery — what `scopes_supported` advertises
// ---------------------------------------------------------------------------
describe('scopesSupportedForDiscovery', () => {
  test('DCR on: exactly the self-registration ceiling, in ALLOWED_SCOPES_LIST order', () => {
    expect(scopesSupportedForDiscovery({ enableDcr: true })).toEqual(['read', 'write']);
  });
  test('DCR off: every scope except operator-only agent and local-CLI-only memory_confirm (the pre-ceiling advertisement)', () => {
    const list = scopesSupportedForDiscovery({ enableDcr: false });
    expect(list).toEqual(['admin', 'read', 'skill_editor', 'skill_publisher', 'skills_member_self', 'sources_admin', 'users_admin', 'write']);
    expect(list).toEqual(ALLOWED_SCOPES_LIST.filter((s) => s !== 'agent' && s !== 'memory_confirm'));
  });
  test('neither list advertises agent (delegation bindings are operator-only)', () => {
    expect(scopesSupportedForDiscovery({ enableDcr: true })).not.toContain('agent');
    expect(scopesSupportedForDiscovery({ enableDcr: false })).not.toContain('agent');
  });
  test('DCR-on list is a subset of DCR_REGISTRABLE_SCOPES and every member passes the DCR ceiling', () => {
    const advertised = scopesSupportedForDiscovery({ enableDcr: true });
    expect(advertised.length).toBeGreaterThan(0);
    for (const s of advertised) expect(DCR_REGISTRABLE_SCOPES.has(s)).toBe(true);
    // A client that copies discovery into its /register request is accepted...
    expect(dcrScopeViolation(advertised, ['authorization_code', 'refresh_token'])).toBeNull();
    // ...and so is each advertised scope on its own.
    for (const s of advertised) expect(dcrScopeViolation([s], ['authorization_code'])).toBeNull();
  });
  test('the DCR-off list would trip the ceiling — which is why DCR-on discovery must narrow', () => {
    expect(dcrScopeViolation(scopesSupportedForDiscovery({ enableDcr: false }), ['authorization_code'])).not.toBeNull();
  });
});