Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

14.1 KB
Raw Blame
import { describe, it, expect, beforeEach, vi } from 'vitest';

// `instances.js` pulls in the socket relay / Tailscale graph; the only thing
// this module and `peerSyncShared` need from it is `getPeers` (the
// UNKNOWN_INSTANCE_ID sentinel this module reads now comes from the real,
// unmocked `instanceIdentity.js` leaf — #6836 — a pure constant, so reading
// it for real costs nothing). Mocking instances.js lets the REAL `findPeerById` /
// `peerAllowsOutbound` / `peerHasCategory` run — which is the point: the test
// asserts pull agrees with push because both use those same predicates.
const peers = [];
vi.mock('../instances.js', async () => ({
  // Real `resolveEffectiveCategories` + shipped defaults, for the same reason:
  // the category-scoped pull decision must agree with what the sync loop and
  // the settings UI resolve for that peer.
  ...(await vi.importActual('../instances.js')),
  getPeers: async () => peers,
}));

let settings = {};
let settingsError = null;
vi.mock('../settings.js', () => ({
  getSettings: async () => {
    if (settingsError) throw settingsError;
    return settings;
  },
}));

const {
  authorizePeerPull,
  decidePeerPull,
  readCallerInstanceId,
  __resetPullWarnThrottleForTests,
  PEER_INSTANCE_ID_HEADER,
  PULL_DENY_UNIDENTIFIED,
  PULL_DENY_UNKNOWN_PEER,
  PULL_DENY_OUTBOUND,
  PULL_DENY_CATEGORY,
} = await import('./peerPullAuthorization.js');
const { peerAllowsOutbound, peerHasCategory } = await import('./peerSyncShared.js');

const PEER_A = 'peer-a-instance-id';
const req = (instanceId) => ({ headers: instanceId ? { [PEER_INSTANCE_ID_HEADER]: instanceId } : {} });

const setPeers = (...next) => {
  peers.length = 0;
  peers.push(...next);
};

// An obviously-fake peer record; `syncCategories.universe` mirrors what the
// push path checks for a `universe` record kind.
const universePeer = (overrides = {}) => ({
  instanceId: PEER_A,
  name: 'Example Peer',
  enabled: true,
  syncEnabled: true,
  directions: ['outbound', 'inbound'],
  syncCategories: { universe: true },
  ...overrides,
});

describe('peerPullAuthorization', () => {
  beforeEach(() => {
    settings = {};
    settingsError = null;
    setPeers();
    __resetPullWarnThrottleForTests();
    vi.restoreAllMocks();
    vi.spyOn(console, 'warn').mockImplementation(() => {});
  });

  describe('readCallerInstanceId', () => {
    it('collapses absent, blank, and sentinel ids to null', () => {
      expect(readCallerInstanceId({ headers: {} })).toBeNull();
      expect(readCallerInstanceId({ headers: { [PEER_INSTANCE_ID_HEADER]: '   ' } })).toBeNull();
      expect(readCallerInstanceId({ headers: { [PEER_INSTANCE_ID_HEADER]: 'unknown' } })).toBeNull();
      expect(readCallerInstanceId({ headers: { [PEER_INSTANCE_ID_HEADER]: ` ${PEER_A} ` } })).toBe(PEER_A);
    });

    it('reads the first value when the header arrived twice', () => {
      expect(readCallerInstanceId({ headers: { [PEER_INSTANCE_ID_HEADER]: [PEER_A, 'other'] } })).toBe(PEER_A);
      expect(readCallerInstanceId({ headers: { [PEER_INSTANCE_ID_HEADER]: `${PEER_A}, other` } })).toBe(PEER_A);
    });
  });

  describe('decidePeerPull', () => {
    it('allows a peer whose sharing config covers the record kind', async () => {
      setPeers(universePeer());
      const decision = await decidePeerPull({ callerId: PEER_A, recordKind: 'universe' });
      expect(decision.allowed).toBe(true);
      expect(decision.reason).toBeNull();
    });

    it('denies an unidentified caller and an unregistered instance id', async () => {
      expect((await decidePeerPull({ callerId: null, recordKind: 'universe' })).reason).toBe(PULL_DENY_UNIDENTIFIED);
      expect((await decidePeerPull({ callerId: 'not-registered', recordKind: 'universe' })).reason).toBe(PULL_DENY_UNKNOWN_PEER);
    });

    it('denies a peer with sync globally disabled or set to inbound-only', async () => {
      setPeers(universePeer({ syncEnabled: false }));
      expect((await decidePeerPull({ callerId: PEER_A, recordKind: 'universe' })).reason).toBe(PULL_DENY_OUTBOUND);
      setPeers(universePeer({ directions: ['inbound'] }));
      expect((await decidePeerPull({ callerId: PEER_A, recordKind: 'universe' })).reason).toBe(PULL_DENY_OUTBOUND);
      setPeers(universePeer({ enabled: false }));
      expect((await decidePeerPull({ callerId: PEER_A, recordKind: 'universe' })).reason).toBe(PULL_DENY_OUTBOUND);
    });

    it('denies a record kind whose category the peer has turned off', async () => {
      setPeers(universePeer());
      const decision = await decidePeerPull({ callerId: PEER_A, recordKind: 'series' });
      expect(decision.reason).toBe(PULL_DENY_CATEGORY);
    });

    it('allows a full-sync peer every subscribable kind', async () => {
      setPeers(universePeer({ syncCategories: {}, fullSync: true }));
      expect((await decidePeerPull({ callerId: PEER_A, recordKind: 'series' })).allowed).toBe(true);
    });

    it('gates a kind-less manifest pull on outbound only, not on categories', async () => {
      setPeers(universePeer({ syncCategories: {} }));
      expect((await decidePeerPull({ callerId: PEER_A })).allowed).toBe(true);
      setPeers(universePeer({ syncCategories: {}, syncEnabled: false }));
      expect((await decidePeerPull({ callerId: PEER_A })).allowed).toBe(false);
    });

    // The acceptance criterion: push and pull decisions come from the SAME
    // predicates, so they can never diverge for a given peer/kind pair.
    it('agrees with the push-path gate for every peer/kind combination', async () => {
      const candidates = [
        universePeer(),
        universePeer({ syncEnabled: false }),
        universePeer({ enabled: false }),
        universePeer({ directions: ['inbound'] }),
        universePeer({ syncCategories: { pipeline: true } }),
        universePeer({ syncCategories: {}, fullSync: true }),
      ];
      for (const peer of candidates) {
        for (const kind of ['universe', 'series', 'mediaCollection']) {
          setPeers(peer);
          const pull = await decidePeerPull({ callerId: PEER_A, recordKind: kind });
          // Exactly the two checks pushRecord runs before sending (peerSyncPush.js).
          const push = peerAllowsOutbound(peer) && peerHasCategory(peer, kind);
          expect(pull.allowed).toBe(push);
        }
      }
    });
  });

  describe('authorizePeerPull compatibility', () => {
    it('serves an unidentified pull when strict mode is off (older peer keeps syncing)', async () => {
      const decision = await authorizePeerPull(req(null), { recordKind: 'universe', route: 'record universe' });
      expect(decision.allowed).toBe(false);
      expect(console.warn).toHaveBeenCalledTimes(1);
    });

    it('warns at most once per caller per boot', async () => {
      await authorizePeerPull(req(null), { recordKind: 'universe' });
      await authorizePeerPull(req(null), { recordKind: 'universe' });
      await authorizePeerPull(req(null), { recordKind: 'series' });
      expect(console.warn).toHaveBeenCalledTimes(1);

      setPeers(universePeer());
      await authorizePeerPull(req(PEER_A), { recordKind: 'series' });
      await authorizePeerPull(req(PEER_A), { recordKind: 'series' });
      expect(console.warn).toHaveBeenCalledTimes(2);
    });

    it('does not warn when the pull is allowed', async () => {
      setPeers(universePeer());
      const decision = await authorizePeerPull(req(PEER_A), { recordKind: 'universe' });
      expect(decision.allowed).toBe(true);
      expect(console.warn).not.toHaveBeenCalled();
    });

    it('403s a denied pull once strictPullAuthorization is on', async () => {
      settings = { federation: { strictPullAuthorization: true } };
      setPeers(universePeer());
      // `severity: 'warning'` is what keeps asyncHandler from re-logging its
      // generic `❌ Route error` on every poll of a peer that will be refused
      // forever; the throttled 🔒 line below is this path's log of record.
      await expect(authorizePeerPull(req(PEER_A), { recordKind: 'series' }))
        .rejects.toMatchObject({ status: 403, code: 'PEER_PULL_FORBIDDEN', severity: 'warning' });
      await expect(authorizePeerPull(req(null), { recordKind: 'universe' }))
        .rejects.toMatchObject({ status: 403 });
      // Strict mode rejects instead of logging the compatibility ⚠️ — but it is
      // not silent: it logs the same throttled 🔒 refusal `alwaysEnforce` does,
      // once per caller. Since the 403 no longer self-logs, this is the only
      // record of a peer being cut off.
      const lines = console.warn.mock.calls.map((c) => c[0]);
      expect(lines).toHaveLength(2);
      for (const line of lines) expect(line).toContain('🔒');
    });

    it('still allows an authorized pull under strict mode', async () => {
      settings = { federation: { strictPullAuthorization: true } };
      setPeers(universePeer());
      expect((await authorizePeerPull(req(PEER_A), { recordKind: 'universe' })).allowed).toBe(true);
    });

    it('treats an unreadable settings file as strict-off (warn, do not break sync)', async () => {
      settingsError = new Error('EACCES');
      const decision = await authorizePeerPull(req(null), { recordKind: 'universe' });
      expect(decision.allowed).toBe(false);
      expect((await authorizePeerPull(req(null), { recordKind: 'universe' })).allowed).toBe(false);
      expect(console.warn).toHaveBeenCalledTimes(1);
      expect(console.warn.mock.calls[0][0]).toContain('⚠️ Serving peer-sync pull to an unidentified caller');
    });
  });

  // #5663 — the snapshot transport's unit of consent is a whole sync CATEGORY,
  // not a record kind, so it resolves the peer's category map directly.
  describe('syncCategory scope', () => {
    it('allows a category the user ticked for this peer', async () => {
      setPeers(universePeer());
      const decision = await decidePeerPull({ callerId: PEER_A, syncCategory: 'universe' });
      expect(decision.allowed).toBe(true);
    });

    it('denies a category the user did NOT tick, even for an outbound-allowed peer', async () => {
      setPeers(universePeer());
      const decision = await decidePeerPull({ callerId: PEER_A, syncCategory: 'digitalTwin' });
      expect(decision).toMatchObject({ allowed: false, reason: PULL_DENY_CATEGORY });
    });

    it('allows anything for a full-sync ("mirror everything") peer', async () => {
      setPeers(universePeer({ fullSync: true, syncCategories: {} }));
      expect((await decidePeerPull({ callerId: PEER_A, syncCategory: 'digitalTwin' })).allowed).toBe(true);
    });

    it('keeps a default-ON category flowing when the master sync switch is off', async () => {
      // `usage` is retained by resolveEffectiveCategories' master-switch mask;
      // gating on peerAllowsOutbound instead would refuse it outright.
      setPeers(universePeer({ syncEnabled: false }));
      expect((await decidePeerPull({ callerId: PEER_A, syncCategory: 'usage' })).allowed).toBe(true);
      expect((await decidePeerPull({ callerId: PEER_A, syncCategory: 'universe' })).allowed).toBe(false);
    });

    it('denies a peer that only announced itself (inbound-only, never approved here)', async () => {
      setPeers(universePeer({ directions: ['inbound'] }));
      // Reason parity with the record routes: "we don't share with you at all"
      // must not read as "we don't share THIS with you".
      expect(await decidePeerPull({ callerId: PEER_A, syncCategory: 'universe' }))
        .toMatchObject({ allowed: false, reason: PULL_DENY_OUTBOUND });
    });

    it('denies a disabled peer as outbound-disallowed, not category-disabled', async () => {
      setPeers(universePeer({ enabled: false }));
      expect(await decidePeerPull({ callerId: PEER_A, syncCategory: 'universe' }))
        .toMatchObject({ allowed: false, reason: PULL_DENY_OUTBOUND });
    });

    it('lets the master switch beat a stale fullSync flag', async () => {
      // `{ fullSync: true, syncEnabled: false }` is reachable (set full mirror,
      // then flip the switch off) and contradictory — every push is already
      // refused for it, so a pull must not hand it the whole install.
      setPeers(universePeer({ fullSync: true, syncEnabled: false }));
      expect((await decidePeerPull({ callerId: PEER_A, syncCategory: 'digitalTwin' })).allowed).toBe(false);
      // The default-ON category still survives the switch, as everywhere else.
      expect((await decidePeerPull({ callerId: PEER_A, syncCategory: 'usage' })).allowed).toBe(true);
    });
  });

  // #5663 — the PII snapshot categories opt out of the warn-first ramp: root
  // AGENTS.md forbids those records on the federation layer at all, so an
  // unidentified caller must never be served one regardless of the setting.
  describe('alwaysEnforce', () => {
    it('403s a denied pull with strictPullAuthorization off', async () => {
      settings = { federation: { strictPullAuthorization: false } };
      await expect(authorizePeerPull(req(null), { route: 'sync digitalTwin', alwaysEnforce: true }))
        .rejects.toMatchObject({ status: 403, code: 'PEER_PULL_FORBIDDEN' });
    });

    it('still allows a configured, outbound-allowed peer', async () => {
      setPeers(universePeer());
      const decision = await authorizePeerPull(req(PEER_A), { route: 'sync digitalTwin', alwaysEnforce: true });
      expect(decision.allowed).toBe(true);
      expect(console.warn).not.toHaveBeenCalled();
    });

    it('logs the refusal once per caller per boot', async () => {
      const opts = { route: 'sync digitalTwin', alwaysEnforce: true };
      await expect(authorizePeerPull(req(null), opts)).rejects.toThrow();
      await expect(authorizePeerPull(req(null), opts)).rejects.toThrow();
      expect(console.warn).toHaveBeenCalledTimes(1);
      expect(console.warn.mock.calls[0][0]).toContain('🔒');
    });

    it('does not consume the served-anyway throttle slot for the same caller', async () => {
      // Distinct throttle keys: a caller refused a PII pull must still produce
      // the one compatibility ⚠️ when it pulls a creative-work category.
      await expect(authorizePeerPull(req(null), { route: 'sync digitalTwin', alwaysEnforce: true })).rejects.toThrow();
      await authorizePeerPull(req(null), { route: 'sync universe' });
      expect(console.warn).toHaveBeenCalledTimes(2);
    });
  });
});