Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

13.7 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import { b64e, newIdentity, sign } from '../lib/e2ee/core.js'
import { acceptTabSession, SHARED_TAB_FRAME_MAX, startTabSession } from '../lib/e2ee/tabSession.js'
import { encodeRoster, fitsRoster, rosterBytes, ROSTER_LIMITS, type Roster } from './roster.js'
import { compose, composeCut, harnessRef, judge, peerKey, sameRoster, shareOf, signedOf, wireHarness } from './sharedTabsRoster.js'

const TAB = 'a1b2c3d4e5f6a1b2c3d4e5f6'
const alice = b64e(newIdentity().pub), bob = b64e(newIdentity().pub), carol = b64e(newIdentity().pub)
const h = (accountId: string, machineId: string, agentId: string, pub: string) => ({ accountId, machineId, machinePublicKey: pub, agentId, name: agentId, engine: 'claude' })
const base: Roster = {
  sharedTabId: TAB, version: 3, name: 'app', leader: null, invites: [],
  owner: { accountId: 'u-alice', email: '[email protected]', machineId: 'm-alice', machinePublicKey: alice },
  members: [{ accountId: 'u-bob', email: '[email protected]', name: 'b', acceptedAt: '2026-10-15T00:00:00.000Z' }],
  harnesses: [h('u-alice', 'm-alice', 'lead', alice), h('u-bob', 'm-bob', 'api', bob)],
}

describe('shared tabs\' pure helpers', () => {
  it('reads a harness off the wire only when every field is what the roster takes', () => {
    expect(wireHarness(h('u-bob', 'm-bob', 'api', bob))).toEqual(h('u-bob', 'm-bob', 'api', bob))
    for (const bad of [null, [], 'x', { ...h('u-bob', 'm-bob', 'api', bob), machinePublicKey: 'short' }, { ...h('u-bob', 'm-bob', 'api', bob), engine: 'e'.repeat(65) },
      { ...h('u-bob', 'm-bob', 'api', bob), agentId: '' }, { ...h('u-bob', 'm-bob', 'api', bob), name: 7 }]) expect(wireHarness(bad)).toBeNull()
    // A name is shown to people and to agents: control and format characters (an escape, a bidi override, a zero-width
    // space) are taken out where the roster is built.
    expect(wireHarness({ ...h('u-bob', 'm-bob', 'api', bob), name: '\u001b[2Ja\u202ep\u200bi\u0000' })?.name).toBe('[2Japi')
    expect(harnessRef({ machineId: 'm', agentId: 'a', extra: 1 })).toEqual({ machineId: 'm', agentId: 'a' })
    expect(harnessRef(null)).toBeNull()
  })

  it('reads a signed roster, with its key change only when whole', () => {
    expect(signedOf({ body: 'b', signature: 's', keyChange: { previousPub: 'p', signature: 'k' } })).toEqual({ body: 'b', signature: 's', keyChange: { previousPub: 'p', signature: 'k' } })
    expect(signedOf({ body: 'b', signature: 's', keyChange: { previousPub: 'p' } })).toEqual({ body: 'b', signature: 's' })
    expect(signedOf({ body: 1, signature: 's' })).toBeNull()
    expect(signedOf('x')).toBeNull()
  })

  it('reads a share as the backend lists it, keeping only members and invitations the roster can hold', () => {
    expect(shareOf({ sharedTabId: TAB, owner: true, ownerEmail: '[email protected]', ownerMachineId: 'm-alice', version: 4, roster: { r: 1 }, tabId: 'tab-1',
      members: [{ userId: 'u-bob', email: '[email protected]', acceptedAt: '2026-10-15T01:02:03Z' }, { userId: 'u-x', email: '[email protected]', acceptedAt: 'never' },
        { userId: 'u-y', email: '[email protected]', acceptedAt: 7 }, null],
      invites: [{ id: 'i1', email: '[email protected]', expiresAt: '2026-11-01T00:00:00.000Z' }, { id: 'i2', email: '[email protected]' }, 'x'] })).toEqual({
      sharedTabId: TAB, owner: true, ownerEmail: '[email protected]', ownerMachineId: 'm-alice', version: 4, roster: { r: 1 }, tabId: 'tab-1',
      members: [{ accountId: 'u-bob', email: '[email protected]', name: 'b', acceptedAt: '2026-10-15T01:02:03.000Z' }],
      invites: [{ email: '[email protected]', expiresAt: '2026-11-01T00:00:00.000Z' }],
      pending: [{ id: 'i1', email: '[email protected]', expiresAt: '2026-11-01T00:00:00.000Z' }],
    })
    // A member's view: no desk tab, no members, no invitations; a version that is not a number reads as none, and an
    // owner's address that is not one as none.
    expect(shareOf({ sharedTabId: TAB, owner: false, ownerEmail: 7, ownerMachineId: 'm-alice', version: '4', roster: null })).toEqual({
      sharedTabId: TAB, owner: false, ownerEmail: '', ownerMachineId: 'm-alice', version: 0, roster: null, tabId: '', members: [], invites: [], pending: [] })
    expect(shareOf({ sharedTabId: TAB, owner: false, ownerEmail: 'x'.repeat(255), ownerMachineId: 'm-alice' })?.ownerEmail).toBe('')
    for (const bad of [null, { sharedTabId: 'tab-1', ownerMachineId: 'm' }, { sharedTabId: TAB }]) expect(shareOf(bad)).toBeNull()
  })

  it('composes the next roster: one entry each, members\' harnesses only while members, a leader only while listed', () => {
    const next = compose(base, { members: [...base.members, base.members[0]], invites: [{ email: '[email protected]', expiresAt: 'x' }, { email: '[email protected]', expiresAt: 'y' }],
      others: [h('u-bob', 'm-bob', 'api', bob), h('u-bob', 'm-bob', 'api', bob), h('u-carol', 'm-carol', 'web', carol), h('u-alice', 'm-alice', 'sneak', alice)],
      leader: { machineId: 'm-bob', agentId: 'api' } })
    expect(next.members).toHaveLength(1)
    expect(next.invites).toEqual([{ email: '[email protected]', expiresAt: 'x' }])
    expect(next.harnesses.map((x) => x.agentId)).toEqual(['lead', 'api'])
    expect(next.leader).toEqual({ machineId: 'm-bob', agentId: 'api' })
    expect(compose(next, { members: [] })).toMatchObject({ leader: null, members: [] })
    expect(compose(base, { own: Array.from({ length: 40 }, (_, i) => h('u-alice', 'm-alice', `a${i}`, alice)) }).harnesses).toHaveLength(ROSTER_LIMITS.harnesses)
    // How many it cut, for the owner to be told (sharedTabs.ts `change`).
    expect(composeCut(base, { own: Array.from({ length: 40 }, (_, i) => h('u-alice', 'm-alice', `a${i}`, alice)) }).cut).toBe(40 + 1 - ROSTER_LIMITS.harnesses)
    expect(composeCut(base, {})).toEqual({ roster: compose(base, {}), cut: 0 })
    expect(sameRoster(base, { ...base, version: 9 })).toBe(true)
    expect(sameRoster(base, { ...base, name: 'other' })).toBe(false)
  })

  it('keeps members by account and invitations by address, whatever order the backend lists them in', () => {
    const m = (accountId: string) => ({ accountId, email: `${accountId}@y.io`, name: accountId, acceptedAt: '2026-10-15T00:00:00.000Z' })
    const i = (email: string) => ({ email, expiresAt: '2026-11-01T00:00:00.000Z' })
    const one = compose(base, { members: [m('u-carol'), m('u-bob'), m('u-dan')], invites: [i('[email protected]'), i('[email protected]'), i('[email protected]')] })
    const other = compose(base, { members: [m('u-dan'), m('u-carol'), m('u-bob')], invites: [i('[email protected]'), i('[email protected]'), i('[email protected]')] })
    expect(one.members.map((x) => x.accountId)).toEqual(['u-bob', 'u-carol', 'u-dan'])
    expect(one.invites.map((x) => x.email)).toEqual(['[email protected]', '[email protected]', '[email protected]'])
    // The same people in another order: the same roster, so nothing is signed again.
    expect(sameRoster(one, other)).toBe(true)
  })

  it('gives the key a machine must prove: the one listed under the account the relay stamped, or, to the owner alone, a member\'s claim', () => {
    expect(peerKey(base, 'm-alice', 'u-alice', undefined, false)).toBe(alice)
    expect(peerKey(base, 'm-alice', 'u-bob', alice, false)).toBeNull()
    expect(peerKey(base, 'm-bob', 'u-bob', carol, false)).toBe(bob)
    expect(peerKey(base, 'm-bob', 'u-carol', carol, true)).toBeNull()
    expect(peerKey(base, 'm-bob2', 'u-bob', carol, true)).toBe(carol)
    expect(peerKey(base, 'm-bob2', 'u-bob', carol, false)).toBeNull()
    expect(peerKey(base, 'm-bob2', 'u-bob', 'short', true)).toBeNull()
    expect(peerKey(base, 'm-carol', 'u-carol', carol, true)).toBeNull()
  })
  describe('judging a member\'s request', () => {
    const carolMember = { accountId: 'u-carol', email: '[email protected]', name: 'c', acceptedAt: '2026-10-15T00:00:00.000Z' }
    const two: Roster = { ...base, members: [...base.members, carolMember] }
    const fromBob = { machineId: 'm-bob', userId: 'u-bob' }

    it('adds a harness only from its own machine, under the key its session proved', () => {
      expect(judge(two, fromBob, bob, 'add', h('u-bob', 'm-bob', 'web', bob))).toEqual({ others: [h('u-bob', 'm-bob', 'api', bob), h('u-bob', 'm-bob', 'web', bob)] })
      // Already listed: nothing to change.
      expect(judge(two, fromBob, bob, 'add', h('u-bob', 'm-bob', 'api', bob))).toBeNull()
    })

    it('refuses an add for another machine than the one asking, even one of the same account', () => {
      expect(judge(two, fromBob, bob, 'add', h('u-bob', 'm-bob2', 'web', carol))).toBe('FORBIDDEN')
      expect(judge(two, fromBob, bob, 'add', h('u-bob', 'm-bob2', 'web', bob))).toBe('FORBIDDEN')
    })

    it('refuses an add on another member\'s machine id the roster does not list yet', () => {
      expect(judge(two, fromBob, bob, 'add', h('u-bob', 'm-carol', 'web', carol))).toBe('FORBIDDEN')
    })

    it('refuses a harness in another account\'s name, on the owner\'s machine, or on a machine listed under another account', () => {
      expect(judge(two, fromBob, bob, 'add', h('u-carol', 'm-bob', 'web', bob))).toBe('FORBIDDEN')
      expect(judge(two, { machineId: 'm-alice', userId: 'u-bob' }, alice, 'add', h('u-bob', 'm-alice', 'web', alice))).toBe('FORBIDDEN')
      expect(judge(two, { machineId: 'm-bob', userId: 'u-carol' }, bob, 'add', h('u-carol', 'm-bob', 'web', bob))).toBe('FORBIDDEN')
      expect(judge(two, { machineId: 'm-dan', userId: 'u-dan' }, carol, 'add', h('u-dan', 'm-dan', 'web', carol))).toBe('FORBIDDEN')
    })

    it('refuses a key that differs from the one the session proved', () => {
      expect(judge(two, fromBob, bob, 'add', h('u-bob', 'm-bob', 'web', carol))).toBe('KEY_MISMATCH')
    })

    it('refuses an add past the harness limit, and a harness that is not one', () => {
      const full: Roster = { ...two, harnesses: Array.from({ length: ROSTER_LIMITS.harnesses }, (_, i) => h('u-alice', 'm-alice', `a${i}`, alice)) }
      expect(judge(full, fromBob, bob, 'add', h('u-bob', 'm-bob', 'web', bob))).toBe('TAB_FULL')
      expect(judge(two, fromBob, bob, 'add', { machineId: 7 })).toBe('INVALID_HARNESS')
    })

    it('refuses an add that would take the roster past what its owner may sign (fitsRoster): TAB_FULL', () => {
      // The tab's name pads the roster to a given room below the most the owner may sign; one more harness here takes
      // about 160 bytes sealed.
      const named = (n: number): Roster => ({ ...two, name: 'x'.repeat(n) })
      let most = 0
      while (fitsRoster(named(most + 1_000))) most += 1_000
      while (fitsRoster(named(most + 1))) most++
      expect(judge(named(most - 60), fromBob, bob, 'add', h('u-bob', 'm-bob', 'web', bob))).toBe('TAB_FULL')
      expect(judge(named(most - 300), fromBob, bob, 'add', h('u-bob', 'm-bob', 'web', bob))).toMatchObject({ others: [h('u-bob', 'm-bob', 'api', bob), h('u-bob', 'm-bob', 'web', bob)] })
    })

    it('lets no roster through that its owner could not send sealed: the worst one the field limits allow fits, or is TAB_FULL', () => {
      // Every field at its limit in the characters JSON writes longest (a lone surrogate: six bytes), the owner and its
      // eight members too; then the member adds the same until it is refused. Each roster it takes is signed and sealed
      // for real, with its key change, and sent as the gateway sends it, to a machine id at the relay's 128 characters.
      const w = (n: number) => '\ud800'.repeat(n)
      const ownerKey = newIdentity(), a = newIdentity(), b = newIdentity(), TAB2 = 'a1b2c3d4e5f6a1b2c3d4e5f6'
      const start = startTabSession(a, TAB2, 'x', 'y')
      const cipher = start.finish(acceptTabSession(b, TAB2, 'x', 'y', start.hello, b64e(a.pub))!.welcome, b64e(b.pub))!
      const frameOf = (r: Roster) => {
        const body = encodeRoster(r), signature = b64e(sign(ownerKey.priv, rosterBytes(r.sharedTabId, r.version, body)))
        const signed = { body, signature, keyChange: { previousPub: alice, signature } }
        return Buffer.byteLength(JSON.stringify({ type: 'amsg_frame', to: 'm'.repeat(128), payload: cipher.seal({ kind: 'roster', signed }) }))
      }
      const bobMachine = `b${w(159)}`, bobs = { machineId: bobMachine, userId: 'u-bob' }
      let roster: Roster = { sharedTabId: TAB2, version: Number.MAX_SAFE_INTEGER, name: w(200), leader: { machineId: w(160), agentId: w(160) },
        owner: { accountId: w(160), email: w(254), machineId: w(160), machinePublicKey: alice },
        members: [{ accountId: 'u-bob', email: w(254), name: w(200), acceptedAt: '2026-10-15T00:00:00.000Z' },
          ...Array.from({ length: ROSTER_LIMITS.members - 1 }, (_, i) => ({ accountId: `${i}${w(159)}`, email: w(254), name: w(200), acceptedAt: '2026-10-15T00:00:00.000Z' }))],
        invites: Array.from({ length: 8 }, (_, i) => ({ email: `${i}${w(253)}`, expiresAt: '2026-11-01T00:00:00.000Z' })),
        harnesses: [{ accountId: w(160), machineId: w(160), machinePublicKey: alice, agentId: w(160), name: w(200), engine: w(64) }] }
      roster.owner.accountId = roster.harnesses[0].accountId
      let verdict: ReturnType<typeof judge> = null
      for (let i = 0; i < ROSTER_LIMITS.harnesses; i++) {
        verdict = judge(roster, bobs, bob, 'add', { accountId: 'u-bob', machineId: bobMachine, machinePublicKey: bob, agentId: `${i}${w(150)}`, name: w(200), engine: w(64) })
        if (typeof verdict === 'string' || !verdict) break
        roster = compose(roster, verdict)
        expect(frameOf(roster)).toBeLessThanOrEqual(SHARED_TAB_FRAME_MAX)
      }
      expect(verdict).toBe('TAB_FULL')
      expect(roster.harnesses.length).toBeLessThan(ROSTER_LIMITS.harnesses)
    })

    it('removes the sender account\'s harness from any machine of that account, and nothing of another\'s', () => {
      expect(judge(two, { machineId: 'm-bob2', userId: 'u-bob' }, carol, 'remove', { machineId: 'm-bob', agentId: 'api' })).toEqual({ others: [] })
      expect(judge(two, fromBob, bob, 'remove', { machineId: 'm-alice', agentId: 'lead' })).toBe('FORBIDDEN')
      expect(judge(two, fromBob, bob, 'remove', { machineId: 'm-bob', agentId: 'ghost' })).toBeNull()
      expect(judge(two, fromBob, bob, 'remove', null)).toBe('INVALID_HARNESS')
    })
  })
})