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.

38.1 KB
Raw Blame
// A13 — per-route identity enforcement on `/control/*` and `/context-link/*`.
//
// Real hook server, real POSTs, spies for the handlers: "refused" here means the handler never ran,
// not that the reply looked unhappy. The properties this file exists to pin:
//
//  - trust on first proof: a node that has never presented a token keeps the legacy path; one that
//    HAS is latched, and an unverified request for it afterwards is refused.
//  - a FOREIGN kid never proves a node and is never caught by the latch — that is what keeps the
//    documented cross-instance failover alive.
//  - the latch is in memory only. Persisting it would let one filesystem accident brick a node
//    forever; a restart must re-earn it, which it does within one hook event.
//  - the dated window: an unverified mutation EXECUTES and carries the restart line until
//    2026-10-13, and is refused with the same shape afterwards.
//  - `write`/`close` keep their user confirmation whatever the token says.
import { describe, it, expect, beforeAll, afterAll, beforeEach, vi } from 'vitest'
import { existsSync, mkdtempSync, rmSync, readdirSync, readFileSync, statSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join, resolve } from 'node:path'
import { hookServer } from './hook-server'
import { nodeAuthToken } from './node-auth-token'
import { nodeTokenDir } from './node-token-files'
import { initNodeTokens, refreshNodeTokens, sweepNodeToken } from './node-token-service'
import {
  IDENTITY_REFUSED_NOTE,
  IDENTITY_RESTART_NOTE,
  IDENTITY_UNMINTABLE_NOTE,
  IDENTITY_UNMINTABLE_WARN_NOTE,
  NODE_IDENTITY_STRICT_AFTER,
  STRICT_CONTROL_REFUSAL,
  STRICT_CONTROL_VERBS,
  TOLERANT_CONTROL_VERBS
} from './node-identity-policy'
import { CONTEXT_LINK_VERBS } from '../context-link-render'
import { initPlatform, resetPlatformForTests } from '../platform'
import { fakePlatform } from '../platform-fake'

const SECRET = Buffer.alloc(32, 11)
// Another instance's secret ⇒ another instance's kid ⇒ the `legacy` failover verdict, NOT `forged`.
const OTHER_SECRET = Buffer.alloc(32, 13)

const IN_WINDOW = new Date('2026-09-01T00:00:00Z')
const PAST_CUTOFF = new Date('2026-11-01T00:00:00Z')

let dir = ''
let controlCalls: { verb: string; nodeId: string }[] = []
let contextCalls: { verb: string; nodeId: string }[] = []

function headers(token?: string): Record<string, string> {
  const h: Record<string, string> = {
    'X-Nodeterm-Hook-Token': hookServer.getToken(),
    'content-type': 'application/x-www-form-urlencoded',
    accept: 'text/plain'
  }
  if (token !== undefined) h['X-Nodeterm-Node-Token'] = token
  return h
}

function control(verb: string, nodeId: string, token?: string, accept = 'text/plain'): Promise<Response> {
  return fetch(`http://127.0.0.1:${hookServer.getPort()}/control/${verb}`, {
    method: 'POST',
    headers: { ...headers(token), accept },
    body: `nodeId=${encodeURIComponent(nodeId)}`
  })
}

function contextLink(verb: string, nodeId: string, token?: string): Promise<Response> {
  return fetch(`http://127.0.0.1:${hookServer.getPort()}/context-link/${verb}`, {
    method: 'POST',
    headers: headers(token),
    body: `nodeId=${encodeURIComponent(nodeId)}`
  })
}

/** A real hook event — the only thing that can put a node in `provenNodes`. */
function hookEvent(nodeId: string, token?: string): Promise<Response> {
  const payload = JSON.stringify({ hook_event_name: 'UserPromptSubmit', session_id: 's', prompt: 'hi' })
  return fetch(`http://127.0.0.1:${hookServer.getPort()}/hook/claude`, {
    method: 'POST',
    headers: headers(token),
    body: `nodeId=${encodeURIComponent(nodeId)}&payload=${encodeURIComponent(payload)}`
  })
}

beforeAll(async () => {
  dir = mkdtempSync(join(tmpdir(), 'hooksrv-identity-'))
  resetPlatformForTests()
  initPlatform(fakePlatform({ userDataDir: dir }))
  await hookServer.start()
  hookServer.setNodeAuthSecret(SECRET)
  hookServer.setControlHandler(async ({ verb, nodeId }) => {
    controlCalls.push({ verb, nodeId })
    return { ok: true, message: `did ${verb}` }
  })
  hookServer.setContextLinkHandler(async ({ verb, nodeId }) => {
    contextCalls.push({ verb, nodeId })
    return 'the linked transcript'
  })
})

afterAll(() => {
  hookServer.setIdentityClockForTests(() => new Date())
  hookServer.setIdentityStrictOverride(() => undefined)
  hookServer.clearNodeAuthSecretForTests()
  hookServer.stop()
  resetPlatformForTests()
  rmSync(dir, { recursive: true, force: true })
})

beforeEach(() => {
  controlCalls = []
  contextCalls = []
  hookServer.setIdentityClockForTests(() => IN_WINDOW)
  hookServer.setIdentityStrictOverride(() => undefined)
})

describe('/control/* during the warning window', () => {
  it('runs an unverified mutation and prefixes the reply with the restart note', async () => {
    const res = await control('open-terminal', 'n-window')
    expect(res.status).toBe(200)
    const body = await res.text()
    // It EXECUTED — that is the promise of the window.
    expect(controlCalls).toEqual([{ verb: 'open-terminal', nodeId: 'n-window' }])
    expect(body.startsWith(IDENTITY_RESTART_NOTE)).toBe(true)
    // …and the reply the agent came for is still there, under the note.
    expect(body).toContain('did open-terminal')
  })

  it('never warns a verified mutation', async () => {
    const res = await control('open-terminal', 'n-verified', nodeAuthToken(SECRET, 'n-verified'))
    expect(res.status).toBe(200)
    const body = await res.text()
    expect(body).not.toContain(IDENTITY_RESTART_NOTE)
    expect(body.trim()).toBe('did open-terminal')
    expect(controlCalls).toHaveLength(1)
  })

  it('lets a tolerant verb through silently — it leaks canvas shape but changes nothing', async () => {
    const res = await control('list', 'n-list')
    expect(res.status).toBe(200)
    expect(await res.text()).not.toContain(IDENTITY_RESTART_NOTE)
    expect(controlCalls).toEqual([{ verb: 'list', nodeId: 'n-list' }])
  })

  it('403s a forged token without a word of advice — nothing legitimate produces one', async () => {
    const forged = nodeAuthToken(SECRET, 'somebody-else')
    const res = await control('open-terminal', 'n-forged', forged)
    expect(res.status).toBe(403)
    expect(controlCalls).toEqual([])
  })
})

describe('/control/* after the cutoff', () => {
  beforeEach(() => {
    hookServer.setIdentityClockForTests(() => PAST_CUTOFF)
  })

  it('refuses an unverified mutation BEFORE the handler runs, with the same sentence', async () => {
    const res = await control('open-terminal', 'n-cutoff')
    expect(res.status).toBe(403)
    expect((await res.text()).trim()).toBe(IDENTITY_REFUSED_NOTE)
    // The point of the feature: nothing happened.
    expect(controlCalls).toEqual([])
  })

  it('answers a JSON caller in JSON, not in text', async () => {
    const res = await control('open-terminal', 'n-cutoff-json', undefined, 'application/json')
    expect(res.status).toBe(403)
    expect(await res.json()).toEqual({ ok: false, error: IDENTITY_REFUSED_NOTE })
    expect(controlCalls).toEqual([])
  })

  it('still lets a verified mutation through', async () => {
    const res = await control('open-terminal', 'n-strict-ok', nodeAuthToken(SECRET, 'n-strict-ok'))
    expect(res.status).toBe(200)
    expect(controlCalls).toHaveLength(1)
  })

  it('still lets an unproven node read the canvas shape', async () => {
    const res = await control('list', 'n-strict-list')
    expect(res.status).toBe(200)
    expect(controlCalls).toEqual([{ verb: 'list', nodeId: 'n-strict-list' }])
  })
})

describe('/context-link/* degrades to prose, never to silence', () => {
  it('takes the legacy path for a node that has never proven itself', async () => {
    const res = await contextLink('transcript', 'n-ctx-legacy')
    expect(res.status).toBe(200)
    expect(await res.text()).toContain('the linked transcript')
    expect(contextCalls).toEqual([{ verb: 'transcript', nodeId: 'n-ctx-legacy' }])
  })

  it('refuses a latched node with a SENTENCE and a 200 — the agent asked for a read', async () => {
    expect((await hookEvent('n-ctx-proven', nodeAuthToken(SECRET, 'n-ctx-proven'))).status).toBe(204)
    const res = await contextLink('transcript', 'n-ctx-proven')
    // Not a 403: the shim turns any non-200 into "nodeterm unreachable", which would be a lie and
    // tells the agent nothing it can act on.
    expect(res.status).toBe(200)
    expect((await res.text()).trim()).toBe(IDENTITY_REFUSED_NOTE)
    expect(contextCalls).toEqual([])
  })

  it('403s a forged token here too', async () => {
    const res = await contextLink('transcript', 'n-ctx-forged', nodeAuthToken(SECRET, 'other'))
    expect(res.status).toBe(403)
    expect(contextCalls).toEqual([])
  })
})

describe('trust on first proof', () => {
  it('is not proven before the first hook event, and is one event later', async () => {
    expect(hookServer.isNodeProven('n-latch')).toBe(false)
    // Before proof, unverified control mutations run (with the note) — the legacy path.
    expect((await control('open-terminal', 'n-latch')).status).toBe(200)
    expect(controlCalls).toHaveLength(1)

    // ONE hook event with this node's own token is the whole ceremony. That is why a restart
    // re-proves immediately and why the latch never needs to be written down.
    expect((await hookEvent('n-latch', nodeAuthToken(SECRET, 'n-latch'))).status).toBe(204)
    expect(hookServer.isNodeProven('n-latch')).toBe(true)

    // After proof, the same tokenless request is refused — the session demonstrably CAN
    // authenticate, so one that suddenly cannot is a different process or a forgery.
    const res = await control('open-terminal', 'n-latch')
    expect(res.status).toBe(403)
    expect((await res.text()).trim()).toBe(IDENTITY_REFUSED_NOTE)
    expect(controlCalls).toHaveLength(1)
  })

  it('latches `list` too — it is not a mutation, but it is still the wrong caller', async () => {
    expect((await hookEvent('n-latch-list', nodeAuthToken(SECRET, 'n-latch-list'))).status).toBe(204)
    expect((await control('list', 'n-latch-list')).status).toBe(403)
    expect(controlCalls).toEqual([])
  })

  it('is released by hookIdentityStrict = false, without downgrading the app', async () => {
    expect((await hookEvent('n-hatch', nodeAuthToken(SECRET, 'n-hatch'))).status).toBe(204)
    expect((await control('open-terminal', 'n-hatch')).status).toBe(403)
    controlCalls = []
    hookServer.setIdentityStrictOverride(() => false)
    const res = await control('open-terminal', 'n-hatch')
    expect(res.status).toBe(200)
    expect((await res.text()).startsWith(IDENTITY_RESTART_NOTE)).toBe(true)
    expect(controlCalls).toHaveLength(1)
  })

  it('is brought forward by hookIdentityStrict = true, before the cutoff', async () => {
    hookServer.setIdentityStrictOverride(() => true)
    const res = await control('open-terminal', 'n-early-strict')
    expect(res.status).toBe(403)
    expect(controlCalls).toEqual([])
  })
})

describe('a foreign kid', () => {
  const FOREIGN = () => nodeAuthToken(OTHER_SECRET, 'n-foreign')

  it('never proves a node', async () => {
    expect((await hookEvent('n-foreign', FOREIGN())).status).toBe(204)
    expect(hookServer.isNodeProven('n-foreign')).toBe(false)
  })

  it('is never caught by the latch — the cross-instance failover has to keep working', async () => {
    // Prove the node with THIS instance's token first, so the latch is armed…
    expect((await hookEvent('n-foreign2', nodeAuthToken(SECRET, 'n-foreign2'))).status).toBe(204)
    expect(hookServer.isNodeProven('n-foreign2')).toBe(true)
    // A TOKENLESS caller is now refused…
    expect((await control('open-terminal', 'n-foreign2')).status).toBe(403)
    // …but a caller holding ANOTHER instance's token is the documented failover, not an impostor,
    // so it gets the window's behaviour: it runs, and it is told to restart.
    const res = await control('open-terminal', 'n-foreign2', nodeAuthToken(OTHER_SECRET, 'n-foreign2'))
    expect(res.status).toBe(200)
    expect((await res.text()).startsWith(IDENTITY_RESTART_NOTE)).toBe(true)
    expect(controlCalls).toEqual([{ verb: 'open-terminal', nodeId: 'n-foreign2' }])
  })
})

/**
 * THE COUNTER-CLAIM, PINNED. Three places in this series used to describe the latch as the feature's
 * security boundary. It is not one, and the difference matters enough to spend a test on: someone
 * reading `controlPolicy` alone will re-derive the stronger claim, because the table really does say
 * `legacy + latched → refuse`.
 *
 * What that table cannot show is who gets to be `legacy`. `verifyNodeToken` reads a token whose
 * `kid` is not ours as FOREIGN ⇒ `legacy`, and invariant 3 requires a foreign kid to never prove and
 * never latch (or the cross-instance failover dies the day a second instance exists). The attacker
 * chooses the kid. So a token made of arbitrary characters is admitted for a latched victim node,
 * while the honest tokenless caller for that same node is refused.
 *
 * The behaviour below is CORRECT and must not be "fixed" — the only hardening that would change it
 * is `node-tokens/<kid>/<nodeId>` (see `writeNodeTokens`), which removes the reason a foreign kid
 * has to be admitted at all. This test exists so the false claim cannot come back.
 */
describe('an invented kid is admitted — the latch is not an adversary boundary', () => {
  // Eight arbitrary characters, a dot, an arbitrary tail: the wire shape, none of the substance.
  // Nothing derives it, nothing on this machine ever held it.
  const INVENTED = 'AAAAAAAA.BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB'

  it('is not a token this instance could ever mint, and is not `forged` either', async () => {
    // Sanity, so the probe below cannot pass for the boring reason that it accidentally IS a token.
    expect(INVENTED).not.toBe(nodeAuthToken(SECRET, 'n-invented'))
    // `forged` would be a 403 on /hook/* — the whole point is that a foreign kid is not judgeable,
    // so it lands on the fail-open verdict instead.
    expect((await hookEvent('n-invented', INVENTED)).status).toBe(204)
    expect(hookServer.isNodeProven('n-invented')).toBe(false)
  })

  for (const [when, clock] of [
    ['during the window', IN_WINDOW],
    ['after the cutoff', PAST_CUTOFF]
  ] as const) {
    it(`walks past the latch into /control/list ${when}, as the victim node`, async () => {
      hookServer.setIdentityClockForTests(() => clock)
      const node = `n-invented-list-${when.replace(/\s/g, '-')}`
      // Arm the latch for real: the victim proves itself with this instance's own token.
      expect((await hookEvent(node, nodeAuthToken(SECRET, node))).status).toBe(204)
      expect(hookServer.isNodeProven(node)).toBe(true)
      // The honest tokenless caller is refused — this is the latch working as designed…
      expect((await control('list', node)).status).toBe(403)
      expect(controlCalls).toEqual([])
      // …and the attacker, who simply made a kid up, is not.
      const res = await control('list', node, INVENTED)
      expect(res.status).toBe(200)
      expect(controlCalls).toEqual([{ verb: 'list', nodeId: node }])
    })

    it(`reads EVERY context-link verb for a latched victim ${when}`, async () => {
      hookServer.setIdentityClockForTests(() => clock)
      const node = `n-invented-ctx-${when.replace(/\s/g, '-')}`
      expect((await hookEvent(node, nodeAuthToken(SECRET, node))).status).toBe(204)
      // Tokenless gets the refusal sentence instead of the transcript.
      expect((await contextLink('transcript', node)).status).toBe(200)
      expect(contextCalls).toEqual([])

      // Every verb the route actually serves, not a hand-picked one: a verb added later must be
      // covered by this claim too, or the doc it pins goes quietly out of date.
      for (const verb of CONTEXT_LINK_VERBS) {
        const res = await contextLink(verb, node, INVENTED)
        expect(res.status, verb).toBe(200)
        // The rendered transcript itself — not the refusal prose. This is the leak.
        expect(await res.text(), verb).toContain('the linked transcript')
      }
      expect(contextCalls).toEqual(CONTEXT_LINK_VERBS.map((verb) => ({ verb, nodeId: node })))
    })
  }

  it('buys nothing extra on a MUTATION after the cutoff — that much the cutoff does hold', async () => {
    // The escape is bounded: `legacy` is still refused for mutations past the date, invented kid or
    // not. What the invented kid defeats is the LATCH, i.e. the tolerant bucket and the window.
    hookServer.setIdentityClockForTests(() => PAST_CUTOFF)
    const res = await control('open-terminal', 'n-invented-mutation', INVENTED)
    expect(res.status).toBe(403)
    expect(controlCalls).toEqual([])
  })
})

describe('the latch is memory, not state', () => {
  it('leaves no trace of a proven node anywhere under the data dir', async () => {
    expect((await hookEvent('n-nopersist', nodeAuthToken(SECRET, 'n-nopersist'))).status).toBe(204)
    expect(hookServer.isNodeProven('n-nopersist')).toBe(true)
    const walk = (root: string): string[] =>
      readdirSync(root).flatMap((entry) => {
        const full = join(root, entry)
        const st = statSync(full)
        // Regular files only: the hook server's own unix socket (issue #367) lives under the data
        // dir too, and a socket is not readable state — opening it is ENXIO, not evidence.
        return st.isDirectory() ? walk(full) : st.isFile() ? [full] : []
      })
    for (const file of walk(dir)) {
      // A persisted latch is a node that one filesystem accident can brick forever. Nothing on
      // disk may know which nodes have proven themselves.
      expect(readFileSync(file, 'utf8'), file).not.toContain('n-nopersist')
    }
  })
})

describe('write/close keep the human in the loop, token or no token', () => {
  it('sends a verified destructive verb to the handler that owns the confirmation', async () => {
    const res = await control('write', 'n-write-v', nodeAuthToken(SECRET, 'n-write-v'))
    expect(res.status).toBe(200)
    // Identity never short-circuits INTO the action: it can only refuse before the handler, never
    // stand in for the dialog the handler puts up.
    expect(controlCalls).toEqual([{ verb: 'write', nodeId: 'n-write-v' }])
  })

  it('sends an unverified destructive verb there too, during the window', async () => {
    const res = await control('close', 'n-close-l')
    expect(res.status).toBe(200)
    expect(controlCalls).toEqual([{ verb: 'close', nodeId: 'n-close-l' }])
    expect((await res.text()).startsWith(IDENTITY_RESTART_NOTE)).toBe(true)
  })

  it('never waves them through as tolerant', () => {
    // The confirm-gated pair (src/shared/control-verbs.ts `isDestructiveVerb`) is untouched by
    // this feature. Tolerance would be the one way identity could weaken it, so it is pinned here;
    // the set itself is covered in canvas-control-core.test.ts.
    expect(TOLERANT_CONTROL_VERBS.has('write')).toBe(false)
    expect(TOLERANT_CONTROL_VERBS.has('close')).toBe(false)
  })
})

describe('an instance with no secret at all', () => {
  it('gates nobody — not even past the cutoff', async () => {
    // safeStorage unavailable on the desktop, an uncreatable key file on the Server Edition. This
    // instance cannot mint a token, so nothing can ever be verified here; warning or refusing
    // `legacy` would hit EVERY caller on the machine with advice that cannot work.
    hookServer.clearNodeAuthSecretForTests()
    hookServer.setIdentityClockForTests(() => PAST_CUTOFF)
    try {
      const res = await control('open-terminal', 'n-nosecret')
      expect(res.status).toBe(200)
      const body = await res.text()
      expect(body).not.toContain(IDENTITY_RESTART_NOTE)
      expect(body.trim()).toBe('did open-terminal')
      expect(controlCalls).toHaveLength(1)
    } finally {
      hookServer.setNodeAuthSecret(SECRET)
    }
  })
})

describe('both shells wire the escape hatch', () => {
  it('is set from settings.hookIdentityStrict in the desktop AND the Server Edition', () => {
    // This repo has shipped a hook-server change to one shell only three times. An unwired shell
    // has no hatch at all, which is the one thing a stranded user cannot work around.
    const root = resolve(__dirname, '../../..')
    for (const rel of ['src/main/index.ts', 'src/server/index.ts']) {
      const src = readFileSync(join(root, rel), 'utf8')
      expect(src, rel).toContain('setIdentityStrictOverride')
      expect(src, rel).toContain('hookIdentityStrict')
    }
  })
})

/**
 * Sweeping a node's token WITHOUT releasing the latch is the one way this feature can kill a live
 * node outright: the latch refuses an unverified caller immediately, on both sides of the cutoff,
 * so the node gets a hard 403 on every canvas-control call for the rest of the session — advised to
 * restart to pick up an identity there is no longer one to pick up.
 *
 * The collision case is the realistic one, and it is a sequence, not a state: the refusal in
 * `node-token-service.ts` is what keeps a fold-collision from becoming a hijack, but it fires the
 * moment the twin appears, which can be long after the first node materialised AND proved itself.
 */
describe('a swept token must also release the latch', () => {
  it('un-proves a node whose case-folding twin turns up and gets the whole set refused', async () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    let hostile = false
    // 1. The node is alone on the canvas, so it gets a token file…
    initNodeTokens({
      canvases: () => [
        { nodes: hostile ? [{ id: 'Term-1' }, { id: 'term-1' }] : [{ id: 'Term-1' }] }
      ]
    })
    expect(existsSync(join(nodeTokenDir(), 'Term-1'))).toBe(true)
    // …and its session proves itself with it.
    expect((await hookEvent('Term-1', nodeAuthToken(SECRET, 'Term-1'))).status).toBe(204)
    expect(hookServer.isNodeProven('Term-1')).toBe(true)

    // 2. A shared `project.json` puts the case-variant twin on the canvas. Both are refused tokens
    //    and both files are swept — correctly: on APFS they are one file, and leaving either is the
    //    hijack. Those nodes belong on `legacy`.
    hostile = true
    refreshNodeTokens()
    expect(existsSync(join(nodeTokenDir(), 'Term-1'))).toBe(false)

    // 3. The live session has nothing left to read, so its next call is tokenless. It must land
    //    back in the warning window, not on a permanent 403 — and it must be told the truth about
    //    WHY, because this node cannot mint until `project.json` changes. This assertion used to
    //    read `IDENTITY_RESTART_NOTE`, which is the loop measured in the field.
    expect(hookServer.isNodeProven('Term-1')).toBe(false)
    const res = await control('open-terminal', 'Term-1')
    expect(res.status).toBe(200)
    expect((await res.text()).startsWith(IDENTITY_UNMINTABLE_WARN_NOTE)).toBe(true)
    expect(controlCalls).toEqual([{ verb: 'open-terminal', nodeId: 'Term-1' }])
    warn.mockRestore()
  })

  it('un-proves a node whose token is swept on delete, closing the re-create gap', async () => {
    // Delete/re-create reuses the id: A6 sweeps the file and rewrites it, and a shell reading in
    // that gap is tokenless while the node is still latched from before the delete.
    initNodeTokens({ canvases: () => [{ nodes: [{ id: 'n-recreate' }] }] })
    expect((await hookEvent('n-recreate', nodeAuthToken(SECRET, 'n-recreate'))).status).toBe(204)
    expect(hookServer.isNodeProven('n-recreate')).toBe(true)
    sweepNodeToken('n-recreate')
    expect(hookServer.isNodeProven('n-recreate')).toBe(false)
    expect((await control('open-terminal', 'n-recreate')).status).toBe(200)
  })

  it('re-earns the latch on the very next valid event — releasing it costs nothing', async () => {
    initNodeTokens({ canvases: () => [{ nodes: [{ id: 'n-relatch' }] }] })
    expect((await hookEvent('n-relatch', nodeAuthToken(SECRET, 'n-relatch'))).status).toBe(204)
    sweepNodeToken('n-relatch')
    expect(hookServer.isNodeProven('n-relatch')).toBe(false)
    expect((await hookEvent('n-relatch', nodeAuthToken(SECRET, 'n-relatch'))).status).toBe(204)
    expect(hookServer.isNodeProven('n-relatch')).toBe(true)
    expect((await control('open-terminal', 'n-relatch')).status).toBe(403)
  })
})

/**
 * The refusal that told a node to restart to pick up an identity that cannot exist.
 *
 * Two populations can never hold a token, however many times they are restarted: a case-folding
 * collision group (refused by design — on APFS they would share one file) and a node id outside
 * `isSafeNodeId`, which reaches the canvas because `fileToProject` does not validate ids read out
 * of `project.json`. Before the cutoff they get the warning window; after it every mutation is
 * refused forever, and `IDENTITY_REFUSED_NOTE` sent them round a restart loop while the only real
 * signal was a `console.warn` in the main-process log.
 */
describe('a node that can NEVER have an identity is told so, and not told to restart', () => {
  beforeEach(() => {
    hookServer.setIdentityClockForTests(() => PAST_CUTOFF)
  })

  it('names the cause for a case-folding collision group, on both dialects', async () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    initNodeTokens({ canvases: () => [{ nodes: [{ id: 'Dup-1' }, { id: 'dup-1' }] }] })
    try {
      const text = await control('open-terminal', 'Dup-1')
      expect(text.status).toBe(403)
      expect((await text.text()).trim()).toBe(IDENTITY_UNMINTABLE_NOTE)
      // Both members of the set, not just the one that lost the race to the shared file.
      const json = await control('open-terminal', 'dup-1', undefined, 'application/json')
      expect(json.status).toBe(403)
      expect(await json.json()).toEqual({ ok: false, error: IDENTITY_UNMINTABLE_NOTE })
      expect(controlCalls).toEqual([])
    } finally {
      warn.mockRestore()
    }
  })

  it('names it for an id `isSafeNodeId` refuses, with nothing registered at all', async () => {
    // No materialiser pass has ever seen this id — the server reads the impossibility off the id.
    for (const nodeId of ['has space', 'a/b', '..', 'x'.repeat(129), '']) {
      const res = await control('open-terminal', nodeId)
      expect(res.status, nodeId).toBe(403)
      expect((await res.text()).trim(), nodeId).toBe(IDENTITY_UNMINTABLE_NOTE)
    }
    expect(controlCalls).toEqual([])
  })

  it('advises no recovery action on the node, because none can work', () => {
    // The contrast, on the axis that matters: the ordinary refusal names a way back (reopen the
    // node — #384 moved it off the in-place "Restart agent", which reuses the same environment and
    // therefore could never help either); this one refuses to name any, because for a colliding or
    // invalid node id there is none short of editing project.json.
    expect(IDENTITY_UNMINTABLE_NOTE).not.toContain('Close and reopen this node')
    expect(IDENTITY_UNMINTABLE_NOTE).not.toContain('Restart')
    expect(IDENTITY_REFUSED_NOTE).toContain('Close and reopen this node')
  })

  it('keeps the ordinary sentence for an ordinary node — the one reopening DOES fix', async () => {
    const res = await control('open-terminal', 'n-ordinary-refusal')
    expect(res.status).toBe(403)
    expect((await res.text()).trim()).toBe(IDENTITY_REFUSED_NOTE)
  })

  it('goes back to the ordinary sentence once the twin leaves the canvas', async () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    let twinned = true
    initNodeTokens({
      canvases: () => [{ nodes: twinned ? [{ id: 'Gone-1' }, { id: 'gone-1' }] : [{ id: 'Gone-1' }] }]
    })
    try {
      expect((await (await control('open-terminal', 'Gone-1')).text()).trim()).toBe(
        IDENTITY_UNMINTABLE_NOTE
      )
      // The twin is removed from `project.json`; the next persist re-materialises the survivor.
      twinned = false
      refreshNodeTokens()
      expect(existsSync(join(nodeTokenDir(), 'Gone-1'))).toBe(true)
      // There IS an identity to pick up now, so the advice to restart is true again.
      expect((await (await control('open-terminal', 'Gone-1')).text()).trim()).toBe(
        IDENTITY_REFUSED_NOTE
      )
    } finally {
      warn.mockRestore()
    }
  })
})

/**
 * THE WINDOW IS WHERE THAT SENTENCE WAS NEEDED, AND IT WAS THE ONE PLACE IT COULD NOT REACH.
 *
 * Measured against a real hook server on 2026-08-14: node `Term-X`, a refused case-fold collision
 * member, was handed `IDENTITY_RESTART_NOTE` — "Close and reopen this node to pick one up" — for a node
 * that has nothing to pick up. `controlPolicy` answers `allow-with-warning` for exactly this
 * population until 2026-10-13, and the warn branch emitted one fixed string, so the unmintable
 * wording only ever appeared AFTER the cutoff (or for a latched node). For the whole warning
 * window — the entire period the note exists to serve — its audience got the restart loop instead.
 */
describe('an unmintable node during the warning window, where the loop actually happens', () => {
  const collide = (a: string, b: string): void => {
    initNodeTokens({ canvases: () => [{ nodes: [{ id: a }, { id: b }] }] })
  }

  it('runs the command AND names the cause instead of advising a restart', async () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    try {
      collide('Warn-1', 'warn-1')
      const res = await control('open-terminal', 'Warn-1')
      // `allow-with-warning`, not a refusal: the window's promise is that the command still runs,
      // and an unmintable node is not a suspect — it is a node whose project.json is wrong.
      expect(res.status).toBe(200)
      expect(controlCalls).toEqual([{ verb: 'open-terminal', nodeId: 'Warn-1' }])
      const body = await res.text()
      expect(body.startsWith(IDENTITY_UNMINTABLE_WARN_NOTE)).toBe(true)
      expect(body).toContain('did open-terminal')
      expect(body).not.toContain(IDENTITY_RESTART_NOTE)
    } finally {
      warn.mockRestore()
    }
  })

  it('says it in the JSON dialect too, in the `warning` field a legacy client parses', async () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    try {
      collide('Warn-2', 'warn-2')
      const res = await control('open-terminal', 'Warn-2', undefined, 'application/json')
      expect(res.status).toBe(200)
      expect(await res.json()).toEqual({
        ok: true,
        message: 'did open-terminal',
        warning: IDENTITY_UNMINTABLE_WARN_NOTE
      })
      expect(controlCalls).toHaveLength(1)
    } finally {
      warn.mockRestore()
    }
  })

  it('says it for an id `isSafeNodeId` refuses, which no materialiser pass has ever seen', async () => {
    // The `project.json` provenance case: `fileToProject` does not validate ids, so a shared repo
    // can put a space (or a slash, or `..`) on the canvas and `nodeAuthToken` returns '' forever.
    for (const nodeId of ['has space', 'a/b', '..']) {
      const res = await control('open-terminal', nodeId)
      expect(res.status, nodeId).toBe(200)
      expect((await res.text()).startsWith(IDENTITY_UNMINTABLE_WARN_NOTE), nodeId).toBe(true)
    }
  })

  it('leaves the ORDINARY unproven node on the restart line — that is the common case', async () => {
    const res = await control('open-terminal', 'n-ordinary-warning')
    expect(res.status).toBe(200)
    const body = await res.text()
    expect(body.startsWith(IDENTITY_RESTART_NOTE)).toBe(true)
    expect(body).not.toContain(IDENTITY_UNMINTABLE_WARN_NOTE)
  })

  it('never tells anyone to Restart, and still names the deadline', () => {
    // The whole point of the pair: no capitalised imperative, because that action cannot work…
    expect(IDENTITY_UNMINTABLE_WARN_NOTE).not.toContain('Restart')
    // …and the same date as the ordinary note, because the same cutoff ends the same window.
    expect(IDENTITY_UNMINTABLE_WARN_NOTE).toContain('2026-10-13')
    // It ran; a sentence copied from the refusal would say the opposite of what just happened.
    expect(IDENTITY_UNMINTABLE_WARN_NOTE).not.toContain('did not run')
  })
})

describe('the injected clock', () => {
  it('is what the cutoff is read against, so a suite crosses it without touching the machine', async () => {
    hookServer.setIdentityClockForTests(() => new Date(NODE_IDENTITY_STRICT_AFTER.getTime() - 1))
    expect((await control('open-terminal', 'n-edge')).status).toBe(200)
    hookServer.setIdentityClockForTests(() => new Date(NODE_IDENTITY_STRICT_AFTER.getTime()))
    expect((await control('open-terminal', 'n-edge2')).status).toBe(403)
  })
})

/**
 * The strict bucket, proven on the wire rather than only in `controlPolicy`'s table.
 *
 * `browser` is the first verb whose admission control IS the identity, so the two escapes this
 * file documents elsewhere — the dated window and `hookIdentityStrict: false` — must both stop at
 * it, and the third (an invented kid, which walks past the latch into /control/list) must stop too.
 * "Refused" here means the handler never ran, not that the reply looked unhappy.
 */
describe('/control/<strict verb> admits only a verified caller', () => {
  const STRICT = 'browser'
  // Same shape as the invented kid above: eight arbitrary characters, a dot, an arbitrary tail.
  const INVENTED = 'CCCCCCCC.DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD'

  it('is in the strict bucket and not in the tolerant one', () => {
    expect(STRICT_CONTROL_VERBS.has(STRICT)).toBe(true)
    expect(TOLERANT_CONTROL_VERBS.has(STRICT)).toBe(false)
  })

  it('refuses a tokenless caller INSIDE the warning window', async () => {
    // Every other mutation still executes here until 2026-10-13. This one never did.
    const res = await control(STRICT, 'n-strict-window')
    expect(res.status).toBe(403)
    expect(await res.text()).toBe(`${STRICT_CONTROL_REFUSAL}\n`)
    expect(controlCalls).toEqual([])
  })

  it('refuses even with the escape hatch OFF — the hatch must not double as a grant', async () => {
    // settings.hookIdentityStrict:false is what docs/node-identity.md tells a stranded user to
    // reach for. Before the bucket it returned allow-with-warning for every non-tolerant verb, so
    // it handed browser control to any holder of the app-wide bearer, permanently.
    hookServer.setIdentityStrictOverride(() => false)
    const res = await control(STRICT, 'n-strict-hatch')
    expect(res.status).toBe(403)
    expect(await res.text()).toBe(`${STRICT_CONTROL_REFUSAL}\n`)
    expect(controlCalls).toEqual([])
    // …while the hatch keeps doing its actual job for an ordinary mutation past the cutoff.
    hookServer.setIdentityClockForTests(() => PAST_CUTOFF)
    const ordinary = await control('open-terminal', 'n-hatch-ordinary')
    expect(ordinary.status).toBe(200)
    expect(controlCalls).toEqual([{ verb: 'open-terminal', nodeId: 'n-hatch-ordinary' }])
  })

  it('lets a VERIFIED caller through, on both sides of the cutoff and with any hatch setting', async () => {
    for (const clock of [IN_WINDOW, PAST_CUTOFF]) {
      for (const override of [undefined, true, false] as const) {
        controlCalls = []
        hookServer.setIdentityClockForTests(() => clock)
        hookServer.setIdentityStrictOverride(() => override)
        const node = `n-strict-ok-${clock.getTime()}-${String(override)}`
        const res = await control(STRICT, node, nodeAuthToken(SECRET, node))
        expect(res.status, node).toBe(200)
        expect(controlCalls, node).toEqual([{ verb: STRICT, nodeId: node }])
      }
    }
  })

  it('403s a forged token, as everywhere else', async () => {
    const res = await control(STRICT, 'n-strict-forged', nodeAuthToken(SECRET, 'somebody-else'))
    expect(res.status).toBe(403)
    expect(controlCalls).toEqual([])
  })

  it('the invented-kid escape does NOT reach a strict verb', async () => {
    // docs/node-identity.md and the test above pin that an invented kid walks past the latch and
    // the cutoff into /control/list and every /context-link/* verb, because a FOREIGN kid must be
    // `legacy` (invariant 3) and `legacy` is admitted there. Here `legacy` is a refusal — one of
    // the very few routes where that escape does not apply. Stated because the surrounding doc's
    // honest pessimism would otherwise be read as covering this verb too.
    const res = await control(STRICT, 'n-strict-invented', INVENTED)
    expect(res.status).toBe(403)
    expect(await res.text()).toBe(`${STRICT_CONTROL_REFUSAL}\n`)
    expect(controlCalls).toEqual([])
    // The contrast, in one test: the SAME token, the same instant, on a tolerant verb.
    const list = await control('list', 'n-strict-invented', INVENTED)
    expect(list.status).toBe(200)
    expect(controlCalls).toEqual([{ verb: 'list', nodeId: 'n-strict-invented' }])
  })

  it('answers a JSON caller with the same sentence in the same shape', async () => {
    const res = await control(STRICT, 'n-strict-json', undefined, 'application/json')
    expect(res.status).toBe(403)
    expect(await res.json()).toEqual({ ok: false, error: STRICT_CONTROL_REFUSAL })
    expect(controlCalls).toEqual([])
  })

  it('says nothing about tokens, kids or restarts — not even to an unmintable node', async () => {
    // An id `isSafeNodeId` refuses normally earns IDENTITY_UNMINTABLE_NOTE, which names the cause
    // and the escape hatch. On a strict verb that sentence would be both an instruction that
    // cannot help (the hatch does not release this) and a map for whoever is probing.
    const res = await control(STRICT, '../etc')
    expect(res.status).toBe(403)
    const body = await res.text()
    expect(body).toBe(`${STRICT_CONTROL_REFUSAL}\n`)
    expect(body).not.toContain(IDENTITY_UNMINTABLE_NOTE)
    expect(body).not.toContain(IDENTITY_REFUSED_NOTE)
    expect(controlCalls).toEqual([])
  })

  it('leaves every other verb on its old table — window, hatch and tolerance all intact', async () => {
    // The regression net for the bucket being a THIRD branch rather than a re-shaping.
    const inWindow = await control('open-terminal', 'n-unchanged-window')
    expect(inWindow.status).toBe(200)
    expect((await inWindow.text()).startsWith(IDENTITY_RESTART_NOTE)).toBe(true)

    hookServer.setIdentityClockForTests(() => PAST_CUTOFF)
    expect((await control('open-terminal', 'n-unchanged-cutoff')).status).toBe(403)
    expect((await control('list', 'n-unchanged-list')).status).toBe(200)

    hookServer.setIdentityStrictOverride(() => false)
    expect((await control('open-terminal', 'n-unchanged-hatch')).status).toBe(200)

    expect(controlCalls).toEqual([
      { verb: 'open-terminal', nodeId: 'n-unchanged-window' },
      { verb: 'list', nodeId: 'n-unchanged-list' },
      { verb: 'open-terminal', nodeId: 'n-unchanged-hatch' }
    ])
  })
})