Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

14.0 KB
Raw Blame
// The decision table, exhaustively. `controlPolicy` is pure on purpose: the routes it governs are
// the two an agent drives with a shell command, and a rule that can only be exercised through a
// socket is a rule nobody can read off a test.
import { describe, it, expect } from 'vitest'
import {
  controlPolicy,
  CONTEXT_LINK_POLICY_VERB,
  IDENTITY_REFUSED_NOTE,
  IDENTITY_RESTART_NOTE,
  isStrictInstant,
  NODE_IDENTITY_CLOCK_HORIZON_MS,
  NODE_IDENTITY_STRICT_AFTER,
  STRICT_CONTROL_REFUSAL,
  STRICT_CONTROL_VERBS,
  TOLERANT_CONTROL_VERBS
} from './node-identity-policy'
import { NODE_IDENTITY_STRICT_DATE } from '@shared/node-identity'

const BEFORE = new Date('2026-09-01T00:00:00Z')
const AFTER = new Date('2026-11-01T00:00:00Z')
const TOLERANT = 'list'
const MUTATION = 'open-terminal'

describe('the cutoff is a dated commitment, not a "later"', () => {
  it('is 2026-10-13, in the source', () => {
    expect(NODE_IDENTITY_STRICT_AFTER.toISOString()).toBe('2026-10-13T00:00:00.000Z')
  })

  it('puts that date in the sentence the user reads', () => {
    expect(IDENTITY_RESTART_NOTE).toContain('2026-10-13')
  })

  it('is built from the ONE date string the Settings row also prints', () => {
    // The renderer cannot import this module, so the date lives in @shared and both sides derive
    // from it. A Settings page promising a different cutoff than the server enforces would be the
    // worst possible version of this feature.
    expect(NODE_IDENTITY_STRICT_DATE).toBe('2026-10-13')
    expect(NODE_IDENTITY_STRICT_AFTER.toISOString().slice(0, 10)).toBe(NODE_IDENTITY_STRICT_DATE)
  })

  it('names an action that CAN work, in both sentences', () => {
    for (const note of [IDENTITY_RESTART_NOTE, IDENTITY_REFUSED_NOTE]) {
      expect(note).toContain('Close and reopen this node')
      // One line: both are PREFIXED onto a reply, and a multi-line prefix buries the reply.
      expect(note).not.toContain('\n')
    }
  })

  it('does NOT prescribe the in-place agent restart, which cannot fix this (#384)', () => {
    // `agent-restart.ts` re-launches the CLI INSIDE the same pane and leaves the pty, the tmux
    // session and therefore the session ENVIRONMENT untouched — and identity is read out of that
    // environment. So the old advice was guaranteed not to work for the population it was handed
    // to, which is the same loop IDENTITY_UNMINTABLE_NOTE was written to break.
    for (const note of [IDENTITY_RESTART_NOTE, IDENTITY_REFUSED_NOTE]) {
      expect(note).not.toContain('Restart agent')
    }
  })

  it('the refusal points at the escape hatch, since it has no date to wait for', () => {
    // IDENTITY_REFUSED_NOTE fires on BOTH sides of the cutoff (the latch does not wait for it), so
    // unlike the warning it cannot tell the user "this becomes strict on <date>". The Settings row
    // is the only thing that releases it without a working fix, and a stranded user's symptom
    // never says "identity", so the sentence has to name it.
    expect(IDENTITY_REFUSED_NOTE).toContain('Settings')
    expect(IDENTITY_REFUSED_NOTE).not.toContain(NODE_IDENTITY_STRICT_DATE)
  })

  it('says, in the refusal, that the command did not run', () => {
    expect(IDENTITY_REFUSED_NOTE).toContain('did not run')
  })
})

describe('the tolerant bucket', () => {
  it('holds `list` and nothing that changes the canvas', () => {
    expect([...TOLERANT_CONTROL_VERBS]).toEqual(['list'])
    // The token is never a substitute for the human's answer, so the confirm-gated verbs are not
    // in here — they must reach the handler (and its dialog), not be waved through by tolerance.
    expect(TOLERANT_CONTROL_VERBS.has('write')).toBe(false)
    expect(TOLERANT_CONTROL_VERBS.has('close')).toBe(false)
  })

  it('is what /context-link/* presents, because every context-link verb is a read', () => {
    expect(TOLERANT_CONTROL_VERBS.has(CONTEXT_LINK_POLICY_VERB)).toBe(true)
  })
})

describe('controlPolicy', () => {
  it('refuses a forged token in every combination — it is the one unambiguous attack signal', () => {
    for (const proven of [false, true]) {
      for (const verb of [TOLERANT, MUTATION]) {
        for (const now of [BEFORE, AFTER]) {
          for (const override of [undefined, true, false]) {
            expect(
              controlPolicy({ verdict: 'forged', proven, verb, now, override }),
              `${proven}/${verb}/${now.toISOString()}/${override}`
            ).toBe('refuse')
          }
        }
      }
    }
  })

  it('allows a verified token in every combination, and never warns it', () => {
    for (const proven of [false, true]) {
      for (const verb of [TOLERANT, MUTATION]) {
        for (const now of [BEFORE, AFTER]) {
          for (const override of [undefined, true, false]) {
            expect(
              controlPolicy({ verdict: 'verified', proven, verb, now, override }),
              `${proven}/${verb}/${now.toISOString()}/${override}`
            ).toBe('allow')
          }
        }
      }
    }
  })

  describe('legacy, before the node has ever proven itself', () => {
    it('takes the legacy path for a tolerant verb, on both sides of the cutoff', () => {
      for (const now of [BEFORE, AFTER]) {
        expect(controlPolicy({ verdict: 'legacy', proven: false, verb: TOLERANT, now })).toBe('allow')
      }
    })

    it('runs a mutation with a warning during the window', () => {
      expect(controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: BEFORE })).toBe(
        'allow-with-warning'
      )
    })

    it('refuses a mutation after the cutoff', () => {
      expect(controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: AFTER })).toBe(
        'refuse'
      )
    })

    it('treats the cutoff instant itself as strict', () => {
      expect(
        controlPolicy({
          verdict: 'legacy',
          proven: false,
          verb: MUTATION,
          now: new Date(NODE_IDENTITY_STRICT_AFTER.getTime())
        })
      ).toBe('refuse')
      expect(
        controlPolicy({
          verdict: 'legacy',
          proven: false,
          verb: MUTATION,
          now: new Date(NODE_IDENTITY_STRICT_AFTER.getTime() - 1)
        })
      ).toBe('allow-with-warning')
    })
  })

  describe('legacy, after the node HAS proven itself — the latch', () => {
    it('refuses, for every verb and on both sides of the cutoff', () => {
      // A session that demonstrably CAN authenticate and suddenly does not is either a different
      // process wearing its node id or a forgery this instance cannot name. Even `list` leaks the
      // canvas shape, so the latch does not exempt it.
      for (const verb of [TOLERANT, MUTATION]) {
        for (const now of [BEFORE, AFTER]) {
          expect(controlPolicy({ verdict: 'legacy', proven: true, verb, now })).toBe('refuse')
        }
      }
    })
  })

  describe('a machine clock that is not to be believed', () => {
    // A VM restored from a snapshot, a board whose RTC came up wrong, a clock somebody set forward:
    // the cutoff is read against `Date.now()`, so any of them puts an ordinary install into strict
    // mode on day one, with no warning window at all and a refusal naming a date "already past".
    // Nothing distinguishes that from an install genuinely still running years later — so the tie
    // goes to the fail-open direction the rest of this file takes.
    const cutoff = NODE_IDENTITY_STRICT_AFTER.getTime()
    const wayAhead = new Date(cutoff + NODE_IDENTITY_CLOCK_HORIZON_MS + 1)

    it('enforces normally right up to the horizon', () => {
      expect(isStrictInstant(new Date(cutoff))).toBe(true)
      expect(isStrictInstant(new Date(cutoff + NODE_IDENTITY_CLOCK_HORIZON_MS - 1))).toBe(true)
    })

    it('stops believing the clock past the horizon and keeps the window open', () => {
      expect(isStrictInstant(wayAhead)).toBe(false)
      expect(isStrictInstant(new Date('2038-01-01T00:00:00Z'))).toBe(false)
      expect(
        controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: wayAhead })
      ).toBe('allow-with-warning')
    })

    it('relaxes only the DATE — the latch and `forged` are untouched by it', () => {
      // The clamp only ever relaxes the DATE. A node that has proven itself is still refused when
      // an unverified caller turns up for it — that is what makes the clamp cheap.
      //
      // NOT because the latch is a security boundary: it is not, and this suite must not be read
      // as saying so. The latch catches a MISTAKE (a session that stopped presenting its token);
      // an attacker invents a `kid`, which is FOREIGN, which is `legacy`, which never latches by
      // invariant 3. See `hook-identity-enforcement.test.ts` → "an invented kid is admitted".
      expect(controlPolicy({ verdict: 'legacy', proven: true, verb: MUTATION, now: wayAhead })).toBe(
        'refuse'
      )
      expect(controlPolicy({ verdict: 'forged', proven: false, verb: TOLERANT, now: wayAhead })).toBe(
        'refuse'
      )
    })

    it('still lets an explicit `true` enforce, wherever the clock thinks it is', () => {
      // The clamp disbelieves the CLOCK, not the user. Someone who asked for strict gets strict.
      expect(
        controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: wayAhead, override: true })
      ).toBe('refuse')
    })

    it('treats an invalid Date as not-strict rather than throwing', () => {
      expect(isStrictInstant(new Date('nonsense'))).toBe(false)
    })
  })

  describe('the hookIdentityStrict escape hatch', () => {
    it('undefined follows the constant', () => {
      expect(
        controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: AFTER, override: undefined })
      ).toBe('refuse')
      expect(
        controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: BEFORE, override: undefined })
      ).toBe('allow-with-warning')
    })

    it('true is strict before the cutoff (opt in early)', () => {
      expect(
        controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: BEFORE, override: true })
      ).toBe('refuse')
    })

    it('false keeps the warning window open past the cutoff, latch included', () => {
      // This is the whole point of the hatch: a user whose upgrade goes wrong gets their canvas
      // back without downgrading the app. It must therefore also release the latch — the latch is
      // the likelier thing to have stranded them.
      expect(
        controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: AFTER, override: false })
      ).toBe('allow-with-warning')
      expect(
        controlPolicy({ verdict: 'legacy', proven: true, verb: MUTATION, now: AFTER, override: false })
      ).toBe('allow-with-warning')
      expect(
        controlPolicy({ verdict: 'legacy', proven: true, verb: TOLERANT, now: AFTER, override: false })
      ).toBe('allow')
    })

    it('never lets a forged token through, whatever it is set to', () => {
      expect(
        controlPolicy({ verdict: 'forged', proven: false, verb: TOLERANT, now: BEFORE, override: false })
      ).toBe('refuse')
    })
  })
})

// The third bucket. Everything above this line is the two-move rollout for verbs that already had
// a population; this is the posture for a verb that never did.
describe('STRICT_CONTROL_VERBS admits `verified` and nothing else', () => {
  const STRICT = 'browser'

  for (const now of [BEFORE, AFTER]) {
    for (const override of [undefined, true, false] as const) {
      for (const proven of [true, false]) {
        const where = `now=${now.toISOString()} override=${override} proven=${proven}`
        it(`verified ⇒ allow (${where})`, () => {
          expect(controlPolicy({ verdict: 'verified', proven, verb: STRICT, now, override })).toBe(
            'allow'
          )
        })
        for (const verdict of ['legacy', 'forged'] as const) {
          it(`${verdict} ⇒ refuse (${where})`, () => {
            expect(controlPolicy({ verdict, proven, verb: STRICT, now, override })).toBe('refuse')
          })
        }
      }
    }
  }

  it('the escape hatch does NOT release it — this is the whole point of the bucket', () => {
    // settings.hookIdentityStrict:false is the switch docs/node-identity.md tells a stranded user
    // to reach for. It releases the latch and the dated cutoff. It must not release this.
    expect(
      controlPolicy({ verdict: 'legacy', proven: false, verb: STRICT, now: BEFORE, override: false })
    ).toBe('refuse')
  })

  it('the dated window does not release it either — refused from day one, not from the cutoff', () => {
    // A tokenless caller would otherwise have driven a browser for the whole warning window.
    expect(
      controlPolicy({ verdict: 'legacy', proven: false, verb: STRICT, now: BEFORE, override: undefined })
    ).toBe('refuse')
  })

  it('a strict verb is in NEITHER tolerant path, ever', () => {
    expect(TOLERANT_CONTROL_VERBS.has(STRICT)).toBe(false)
    expect(STRICT_CONTROL_VERBS.has(STRICT)).toBe(true)
    expect([...STRICT_CONTROL_VERBS].some((v) => TOLERANT_CONTROL_VERBS.has(v))).toBe(false)
  })

  it('leaves every other verb exactly as it was', () => {
    // The regression net: the bucket is a THIRD branch, not a re-shaping of the other two.
    expect(
      controlPolicy({ verdict: 'legacy', proven: false, verb: TOLERANT, now: AFTER, override: undefined })
    ).toBe('allow')
    expect(
      controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: BEFORE, override: undefined })
    ).toBe('allow-with-warning')
    expect(
      controlPolicy({ verdict: 'legacy', proven: false, verb: MUTATION, now: AFTER, override: undefined })
    ).toBe('refuse')
    expect(
      controlPolicy({ verdict: 'legacy', proven: true, verb: MUTATION, now: AFTER, override: false })
    ).toBe('allow-with-warning')
  })

  it('says one sentence and diagnoses nothing — advice here is advice to whoever is probing', () => {
    expect(STRICT_CONTROL_REFUSAL).toBe('Browser control refused.')
    expect(STRICT_CONTROL_REFUSAL).not.toContain('\n')
    for (const leak of ['token', 'kid', 'Restart', 'identity']) {
      expect(STRICT_CONTROL_REFUSAL).not.toContain(leak)
    }
  })
})