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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
/**
* What a per-node token BUYS, per route: the policy that turns the three-way verdict from
* `verifyNodeToken` into allow / allow-with-warning / refuse.
*
* The whole identity series up to here is measurement — it can say `verified`, `legacy`, `forged`
* and it labels events with the answer, but nothing has ever DEPENDED on it. This file is where it
* starts to. That is the dangerous half, because the population it governs is already running:
* tmux sessions outlive the app, so on the day this ships there are live agent sessions holding a
* launcher, a skill shim and an environment from before the token existed. Enforce on day one and
* their next `manage-nodeterm-canvas` call stops working with no way for them to know why.
*
* So enforcement arrives in two moves, and both are here rather than scattered through the routes:
*
* 1. TRUST ON FIRST PROOF. A node that has never presented a token this instance minted keeps the
* legacy path. A node that HAS is latched: an unverified request naming it afterwards is
* refused, because that session demonstrably CAN authenticate and one that suddenly cannot is
* either a different process wearing its node id or a forgery this instance cannot name. The
* latch costs the legacy population nothing — they never prove anything, so they never latch.
*
* 2. A DATED WINDOW. Until `NODE_IDENTITY_STRICT_AFTER` an unverified MUTATION still executes and
* the reply carries `IDENTITY_RESTART_NOTE`, which names the fix and the date. After it, the
* same situation is a refusal. The date is in the source, not in a comment saying "later":
* a tightening with no date is a tightening that never happens.
*/
import { NODE_IDENTITY_STRICT_DATE } from '@shared/node-identity'
import type { NodeTokenVerdict } from './node-auth-token'
/**
* When an unverified mutation stops executing and starts being refused.
*
* Built from the ONE date string in `@shared/node-identity` — the Settings row prints that same
* string, and the renderer cannot import this file. See there for where the date comes from.
*/
export const NODE_IDENTITY_STRICT_AFTER = new Date(`${NODE_IDENTITY_STRICT_DATE}T00:00:00Z`)
const STRICT_DATE = NODE_IDENTITY_STRICT_DATE
/**
* How far past the cutoff the LOCAL CLOCK may read before the cutoff stops being believed at all.
*
* The cutoff is compared against `Date.now()`, and a machine clock is not evidence. A VM restored
* from a snapshot, a board whose RTC came up wrong, or a clock somebody set forward on purpose can
* put a perfectly ordinary install years into the future — and it then enters strict mode on day
* one, with no warning window, refusing every unverified mutation with a sentence naming a date
* that has "already passed". The symptom reads as "the token is broken", so nobody looks at the
* clock, and the escape hatch is the last place they think to go.
*
* There is no way to tell that case apart from an install genuinely still running years after the
* cutoff: an old binary can run forever, so `now` far ahead of anything in this source proves
* nothing on its own. Since the two are indistinguishable, the tie is broken by which mistake is
* worse — and the whole series fails OPEN by design, so the answer is to keep the window open.
*
* That costs almost nothing, and it is worth being exact about WHY, because the obvious reason is
* false. **Neither the cutoff nor the latch is a boundary against an attacker.** The latch protects
* against a MISTAKE — a session that silently stopped presenting its token. It cannot protect
* against an adversary, because an adversary picks the `kid`: a made-up `kid` is a FOREIGN kid,
* which invariant 3 requires to be `legacy` and never latched (or cross-instance failover dies), so
* an invented token walks past the latch AND the cutoff into `/control/list` and every
* `/context-link/*` read. Measured against the real server and pinned in
* `hook-identity-enforcement.test.ts` ("an invented kid is admitted"); see docs/node-identity.md.
*
* So the clamp is cheap for a smaller and more honest reason: what it relaxes is only the
* population that has NEVER proven anything, i.e. exactly the pre-token sessions the warning window
* exists for, and fail-open is that population's designed state. It relaxes the DATE and nothing
* else — `forged` and the latch are untouched by it.
*
* Two years, because that is comfortably longer than the upgrade population survives (tmux sessions
* and un-updated installs do not last it out) and comfortably shorter than the clock skews that
* actually occur, which are measured in decades (an RTC default year, an epoch reset, a licence
* clock set forward).
*
* The same reasoning as `license.ts`'s rollback anchor, pointed the other way: there, the clock
* direction the USER benefits from (setting it back to revive an expired token) is the one that is
* refused, via `Math.max(Date.now(), lastSeen)`. Here the direction a user benefits from is setting
* the clock BACK to dodge the cutoff — and that buys them nothing worth defending, because
* `hookIdentityStrict: false` grants exactly the same thing with one click. So there is no security
* to trade away by disbelieving a clock that reads absurdly far forward; there is only a silent
* day-one lockout to remove.
*/
export const NODE_IDENTITY_CLOCK_HORIZON_MS = 2 * 365 * 24 * 60 * 60 * 1000
/**
* Is `now` an instant at which the dated cutoff should be enforced?
*
* Clamped at BOTH ends: before the cutoff the window is open (the point of the window), and beyond
* `NODE_IDENTITY_CLOCK_HORIZON_MS` past it the clock is not believed and the window is open again.
* Exported so the clamp is testable as a rule rather than only through `controlPolicy`'s table.
*/
export function isStrictInstant(now: Date): boolean {
const t = now.getTime()
const cutoff = NODE_IDENTITY_STRICT_AFTER.getTime()
// NaN (an invalid Date from a broken injected clock) fails both comparisons ⇒ not strict, which
// is the fail-open direction this whole file takes.
return t >= cutoff && t < cutoff + NODE_IDENTITY_CLOCK_HORIZON_MS
}
/**
* Prefixed onto the reply of an unverified mutation that STILL RAN.
*
* It says what could not be established, that the command ran anyway, the exact action that fixes
* it, and the date after which it stops being a note and starts being a refusal. One line, because
* it is a prefix and a multi-line prefix buries the reply the agent actually asked for.
*
* THE ACTION IS "close and reopen", not "Restart agent" — issue #384. Both sentences used to name
* the in-place restart, and that one is measurably incapable of fixing this: `agent-restart.ts`
* types the CLI's exit line and re-launches it INSIDE the same pane, deliberately leaving the pty,
* the tmux session and therefore the whole session ENVIRONMENT untouched. Identity is read out of
* that environment (`$NODETERM_HOOK_ENDPOINT` → the token dir it advertises), so the restart
* cannot change the answer, however many times it is run. Only a new tmux session picks up the
* current `-e` env, and on an SSH host only a reconnect rewrites the endpoint file, the shim, the
* hook script and the token files. Naming an action that cannot work is the exact loop
* `IDENTITY_UNMINTABLE_NOTE` exists to break, and it was being handed to a far larger population.
*/
export const IDENTITY_RESTART_NOTE =
'NodeTerm could not confirm which node sent this command: this session is not presenting its ' +
'node identity, so it ran unverified. Close and reopen this node to pick one up (on an SSH ' +
`project, reconnect the project first) — from ${STRICT_DATE} commands from a session without ` +
'one are refused.'
/**
* The same situation once it is refused — after the cutoff, or once the node has proven itself and
* an unverified caller turns up anyway.
*
* Deliberately carries NO date: it fires on both sides of the cutoff (the latch does not wait for
* it), and a sentence that says "since <date>" would be false for half of the cases it answers.
*/
export const IDENTITY_REFUSED_NOTE =
'NodeTerm could not confirm which node sent this command, so it did not run: this session is ' +
'not presenting its node identity. Close and reopen this node to pick one up — on an SSH ' +
'project, reconnect the project first — or turn off Settings → Agents → "Require verified node ' +
'identity for canvas control".'
/**
* The refusal for a node that can NEVER have an identity, however many times it is restarted.
*
* Two populations land here, and both are permanent until a FILE is edited:
*
* - a node whose id case-folds onto another id on the same canvas. The materialiser refuses tokens
* for the whole colliding set on purpose (`node-token-service.ts`) — on APFS they would be one
* file, and that is the hijack.
* - a node whose id is outside `[A-Za-z0-9._-]`, or `.`/`..`/empty/over-length. `fileToProject`
* does not validate ids read out of `project.json`, so such an id reaches the canvas intact and
* `nodeAuthToken` returns '' for it forever.
*
* Giving those `IDENTITY_REFUSED_NOTE` is the worst kind of wrong answer: it names an action
* ("Close and reopen this node to pick one up") that is guaranteed not to work, so the user
* reopens in a loop while the only real signal — a `console.warn` in the main-process log — sits
* somewhere they will never look. This sentence names the cause instead, refuses to advise any
* action on the node, and points at both real ways out: fix the id, or use the escape hatch,
* which does release this.
*
* It is one of a PAIR: this is the refusal, `IDENTITY_UNMINTABLE_WARN_NOTE` is the same cause said
* during the warning window, where the command ran. The two differ in one clause and share the
* rest, because the cause and the way out do not depend on which side of the cutoff you are on.
*/
const UNMINTABLE_CAUSE =
'this node can never present an identity, so restarting it will not help: its node id is ' +
"invalid, or it collides with another node id in this project's project.json when letter case " +
'is ignored. Fix the duplicate or invalid id there, or turn off Settings → Agents → "Require ' +
'verified node identity for canvas control".'
export const IDENTITY_UNMINTABLE_NOTE =
'NodeTerm could not confirm which node sent this command, so it did not run — and ' +
UNMINTABLE_CAUSE
/**
* The same cause during the WARNING WINDOW, where the command still ran.
*
* This sentence is the whole reason the unmintable case needed a second one. `IDENTITY_UNMINTABLE_
* NOTE` is a refusal and says "so it did not run"; the window is `allow-with-warning`, so pasting
* the refusal on top of a reply that plainly DID run swaps one false sentence for another. And
* `IDENTITY_RESTART_NOTE` — what these nodes got until now — is the exact loop the unmintable
* wording exists to break, delivered for the entire window the note was written to serve: the user
* restarts, the node still cannot mint, the note comes back unchanged.
*
* It keeps `IDENTITY_RESTART_NOTE`'s closing clause verbatim, because the deadline is the same one
* and it is the part that makes the advice urgent: on the cutoff this stops being a note.
*/
export const IDENTITY_UNMINTABLE_WARN_NOTE =
'NodeTerm could not confirm which node sent this command, so it ran unverified — and ' +
UNMINTABLE_CAUSE +
` From ${STRICT_DATE} commands from a session without an identity are refused.`
/**
* Control verbs that an unproven, unverified caller may still run after the cutoff.
*
* `list` is the whole bucket: it leaks the shape of the canvas — node ids, titles, which agent is
* where — and it changes nothing. Refusing it would break every legacy client's ability to even
* ORIENT itself, permanently, for a leak that a caller already holding the shared bearer could get
* from a dozen other places. Nothing that acts on the canvas belongs in here, and in particular not
* the confirm-gated pair (`write`, `close`): tolerance would be the one way this feature could
* weaken the human confirmation, which it must never do.
*/
export const TOLERANT_CONTROL_VERBS = new Set(['list'])
/**
* Control verbs that admit ONLY a `verified` caller — no window, no latch, no override.
*
* ⚠ **PRE-POSITIONED, AND INERT TODAY.** `browser` is the whole bucket, and `browser` is **not a
* verb this app has**: `ControlVerb` (`src/core/canvas-control-core.ts`) lists 24 and the browser
* one is `open-browser`, which is deliberately NOT in here (see below). So measured over the real
* verb list, this set changes nothing for anybody: no request that succeeds today starts failing,
* and `hookIdentityStrict: false` releases exactly what it released before. What it does is make
* the ordering correct BEFORE the verb exists, so the verb cannot arrive through the hole. The
* hole was real — the `override === false` branch below returns `allow-with-warning` for every
* non-tolerant verb — and a route that acts as the user on the internet must not be the thing that
* discovers it.
*
* The verb it is for is a route through which an agent acts as the user on the internet, inside a
* session jar that may hold real logins, and it is NEW — so unlike every verb the two-move rollout
* was built for, there is no legacy population to strand and nothing to fail open FOR. Same posture
* `/codex-thread/{start,bind}` already holds, for the same reason.
*
* **Why `open-browser` is NOT in here, deliberately.** OPENING a node is not DRIVING one. The
* threat this bucket answers is an agent acting *inside* a page the user is logged into — reading
* cookies, typing, evaluating script; `open-browser` only creates the surface and navigates it to
* a URL the caller supplied, which is the same class of act as `show-web`. And it is a SHIPPED
* verb with a live legacy population: adding it would mean an agent session that has not picked up
* a token (a pre-token tmux session, or an SSH host whose project has not reconnected) loses the
* ability to open a browser node with no way back — the hatch cannot rescue it, because the whole
* point of this bucket is that the hatch does not reach it. That is precisely the stranding the
* dated window exists to prevent, paid to defend a surface that holds nothing yet. The residual is
* named rather than hidden: an unverified caller can open a node onto a logged-in page, and the
* page's TITLE then appears in `list`. That leak belongs to `list`'s tolerance, is unchanged by
* this file, and is the pre-existing trade documented on TOLERANT_CONTROL_VERBS.
*
* So: this doc comment claims a gate on DRIVING a browser, never on opening one. When the real
* verb lands it joins this set in the PR that creates it, and that PR — not this one — is where a
* user-visible behaviour change begins.
*
* Checked BEFORE the `override === false` branch, deliberately. That branch returns
* `allow-with-warning` for any non-tolerant verb, so `settings.hookIdentityStrict: false` — the
* switch docs/node-identity.md tells a stranded user to reach for — would otherwise hand browser
* control to any holder of the app-wide bearer, permanently. The escape hatch exists to rescue a
* session that cannot present an identity; it must not double as a grant of the one capability
* where identity is the entire admission control.
*
* WHAT IT BUYS, precisely: an invented `kid` is a FOREIGN kid, which invariant 3 requires to be
* `legacy` (or cross-instance failover dies), so it walks past the latch and the cutoff into
* /control/list and every /context-link/* read. Here `legacy` is a refusal, so that probe fails.
*
* WHAT IT COSTS: cross-instance failover loses browser control. A second instance's token is a
* foreign kid, therefore `legacy`, therefore refused. Accepted. A verb must NEVER be moved from
* here into TOLERANT_CONTROL_VERBS.
*/
export const STRICT_CONTROL_VERBS: ReadonlySet<string> = new Set(['browser'])
/**
* The refusal for a strict verb: one sentence, no diagnosis, no hint about tokens or kids.
* Advice here is advice to an attacker and a lie to nobody else — the doc's own phrasing for the
* `forged` case, applied to the whole non-`verified` set.
*/
export const STRICT_CONTROL_REFUSAL = 'Browser control refused.'
/**
* The verb `/context-link/*` presents to `controlPolicy`.
*
* Every context-link verb is a READ — the route hands back a rendered transcript, summary or
* terminal capture and changes nothing — so the whole route belongs in the same bucket as `list`.
* Saying that with a named constant keeps it ONE bucket rather than two lists that drift.
*/
export const CONTEXT_LINK_POLICY_VERB = 'list'
export type IdentityDecision = 'allow' | 'allow-with-warning' | 'refuse'
export interface ControlPolicyInput {
/** What `verifyNodeToken` made of the presented header. */
verdict: NodeTokenVerdict
/**
* Has THIS node ever presented a token this instance minted for it?
*
* The caller is responsible for one subtlety: a FOREIGN kid (another instance's token — the
* documented cross-instance failover) must arrive here as `proven: false`, even for a node that
* has latched. It is `legacy` for the same reason it is `legacy` in `verifyNodeToken`: this
* instance has no standing to judge another instance's credential, and latching against one
* would break failover on the day a second instance appears.
*/
proven: boolean
/** The control verb; `CONTEXT_LINK_POLICY_VERB` for a context-link read. */
verb: string
/** Injected, never `Date.now()` inside: a suite has to be able to stand on both sides of the
* cutoff without touching the machine clock. */
now: Date
/** `settings.hookIdentityStrict`. `undefined` ⇒ follow the constant. */
override?: boolean
}
/**
* Pure. Every route decision in this feature comes from this one table:
*
* forged → refuse (the one unambiguous attack signal)
* verified → allow
* legacy + latched → refuse (trust on first proof)
* legacy + tolerant verb → allow (the legacy population's read path)
* legacy + mutation, inside the window → allow-with-warning
* legacy + mutation, past the cutoff → refuse
*
* `override === false` is the escape hatch: it releases the LATCH as well as the cutoff, because
* the latch is the likelier of the two to have stranded a user whose upgrade went wrong, and a
* hatch that does not rescue them is not a hatch. It never releases `forged`, and it never
* releases a verb in `STRICT_CONTROL_VERBS` — that bucket is decided one line below `forged`,
* above every branch the hatch can reach.
*/
export function controlPolicy({
verdict,
proven,
verb,
now,
override
}: ControlPolicyInput): IdentityDecision {
if (verdict === 'forged') return 'refuse'
// BEFORE the override and BEFORE the dated window — see STRICT_CONTROL_VERBS.
if (STRICT_CONTROL_VERBS.has(verb)) return verdict === 'verified' ? 'allow' : 'refuse'
if (verdict === 'verified') return 'allow'
if (override === false) {
return TOLERANT_CONTROL_VERBS.has(verb) ? 'allow' : 'allow-with-warning'
}
if (proven) return 'refuse'
if (TOLERANT_CONTROL_VERBS.has(verb)) return 'allow'
// `isStrictInstant`, not a bare `>=`: a machine clock years ahead of the cutoff would otherwise
// put this install in strict mode on day one with no warning window at all. See the constant.
const strict = override ?? isStrictInstant(now)
return strict ? 'refuse' : 'allow-with-warning'
}