favela-peer / test / browsers-bootstrap.test.js

// Making TOFU safe on a surface that is NOT loopback.
//
// ⛔ THE PREMISE THAT BREAKS. browsers.js says it plainly: the safety of first-claim TOFU "rests
// ENTIRELY on the surface binding localhost… exposing it before claiming it hands it to whoever is on
// the network. It is a first-run convenience, not an authorisation model." A bridge's operator page has
// to be reachable from the network, so "the first browser to prove a key" becomes "the first stranger
// who finds the port".
//
// ⛔ AND THE RACE STOPS BEING THEORETICAL. The same header admits `claim` reads `unclaimed()` and then
// writes: "two browsers arriving together can both read 'nobody registered'". On loopback that gap is
// one round trip. On a public port it is something an attacker can drive on purpose.
//
// A bootstrap token the CALLER prints to its own service log is a secret only the operator can read,
// so requiring it for the FIRST claim binds that claim to them without inventing an authorisation
// model. A latch makes the check-and-register atomic.
//
// ⚠ No token configured means NOT REQUIRED — the loopback default, unchanged, which is why every
// existing browsers test still passes untouched.

import test from 'brittle'
import Corestore from 'corestore'
import fs from '#node:fs'
import os from '#node:os'
import { join } from '#node:path'
import { an } from 'anproto'
import { Browsers } from '../lib/browsers.js'

const tmp = () => fs.mkdtempSync(join(os.tmpdir(), 'favela-bootstrap-'))
const TOKEN = 'b7f4c1a9e2d05638b7f4c1a9e2d05638'

async function open (opts) {
  const b = new Browsers(new Corestore(tmp()), opts)
  await b.ready()
  return b
}

async function browser () {
  const keypair = await an.gen()
  return {
    publicKey: an.publicKey(keypair),
    async answer (b) {
      const { challenge } = b.challenge()
      return { challenge, signature: await an.sign(await an.hash(challenge), keypair) }
    }
  }
}

test('★★★ with a bootstrap token set, a proved key alone cannot claim', async (t) => {
  const b = await open({ bootstrap: TOKEN })
  const who = await browser()

  // ⚠ The answer is taken BEFORE the arrow: `await` inside a non-async arrow is a parse error, not a
  // runtime one, so it takes the whole file down rather than the test.
  const proof = await who.answer(b)
  await t.exception(
    () => b.claim({ publicKey: who.publicKey, ...proof }),
    /bootstrap token/,
    'proving the key is not enough on a surface strangers can reach')

  t.ok(await b.unclaimed(), 'and the refusal changed nothing — the instance is still unclaimed')
})

test('★★★ a wrong token is refused and costs nothing', async (t) => {
  const b = await open({ bootstrap: TOKEN })
  const who = await browser()

  const proof = await who.answer(b)
  await t.exception(
    () => b.claim({ publicKey: who.publicKey, ...proof, bootstrap: 'b7f4c1a9e2d05638b7f4c1a9e2d05639' }),
    /bootstrap token/,
    'one byte different is still wrong')
  t.ok(await b.unclaimed(), 'nothing was written')
})

test('★★★ the right token claims it, once', async (t) => {
  const b = await open({ bootstrap: TOKEN })
  const first = await browser()

  const firstProof = await first.answer(b)
  const out = await b.claim({ publicKey: first.publicKey, ...firstProof, bootstrap: TOKEN })
  t.ok(out.claimed)
  t.absent(await b.unclaimed(), 'the instance is claimed')

  // ⛔ It closes PERMANENTLY. Holding the token does not reopen it — the token gates the first claim,
  // it is not a standing key to the instance.
  const second = await browser()
  const secondProof = await second.answer(b)
  await t.exception(
    () => b.claim({ publicKey: second.publicKey, ...secondProof, bootstrap: TOKEN }),
    /already claimed/,
    'a second claimant with the same token is still refused')
})

test('★★★ two claimants arriving together — exactly one wins', async (t) => {
  // The race the header admits. Both prove their key, both present the token, both arrive before
  // either has written. Without the latch both read "unclaimed" and both register.
  const b = await open({ bootstrap: TOKEN })
  const a1 = await browser()
  const a2 = await browser()

  const proofs = [
    { publicKey: a1.publicKey, ...(await a1.answer(b)), bootstrap: TOKEN },
    { publicKey: a2.publicKey, ...(await a2.answer(b)), bootstrap: TOKEN }
  ]
  const results = await Promise.allSettled(proofs.map((p) => b.claim(p)))

  const won = results.filter((r) => r.status === 'fulfilled')
  const lost = results.filter((r) => r.status === 'rejected')
  t.is(won.length, 1, 'exactly one claim succeeded')
  t.is(lost.length, 1, 'and the other was told the instance was already claimed')
  // ⚠ Guarded. Without the latch BOTH claims succeed and `lost` is empty — measured — so an
  // unguarded `lost[0].reason` throws and takes the whole FILE down instead of failing this one
  // assertion. A test that crashes on the defect it exists to catch reports nothing.
  const why = lost.length ? String((lost[0].reason && lost[0].reason.message) || lost[0].reason) : '(nobody lost — both claims won)'
  t.ok(/already claimed/.test(why), why)
})

test('★★ with no token configured nothing changes — the loopback default', async (t) => {
  const b = await open()
  const who = await browser()
  const proof = await who.answer(b)
  const out = await b.claim({ publicKey: who.publicKey, ...proof })
  t.ok(out.claimed, 'first-claim TOFU still works where the surface is bound to localhost')
})