~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
382 lines · 21.2 KB Raw History
// The spaces run: the server beside the pinned spaces alpha of the
// reference PDS, on the alpha's PLC directory, in each part the server
// plays (spec/SPACES.md, "Who takes part", "Test vectors"). It checks
// the spaces test vectors first, then sends both sides the same requests and
// compares what spaces change: each account's KEM key, in its genesis
// operation, its DID document and getRecommendedDidCredentials, across a
// handle change and a restart; describeServer's spacesAlpha; each
// account's space repos (repo.mjs, spec/SPACES-REPO.md), written into spaces
// an authority on the alpha's second PDS made, read back, and read again
// after the restart, with each repo whole as a STAR archive, the blobs its
// records reference, and imported repos (export.mjs,
// spec/SPACES-EXPORT.md); spaces' credentials, with that second alpha PDS, the
// peer, in the roles the server is not playing (credentials.mjs,
// spec/SPACES-CREDENTIALS.md); and then the policies and the space lifecycle
// (policies.mjs, spec/SPACES-POLICIES.md), with the server as a space's
// authority beside alpha peers on the second alpha PDS; then OAuth `space:`
// permissions, with space type declarations a third PDS publishes
// (scopes.mjs, spec/OAUTH-SCOPES.md, "Spaces"); and last, the
// server alone, the guard every request the spaces make goes through, with
// the server started again with SSRF protection on (ssrf.mjs), and how it
// keeps issuers' keys, started again with a short PDS_DID_CACHE_SECS
// (issuers.mjs). It stops at the first thing that differs, saying what was
// asked and what each answered.
//
//   cd harness/spaces && npm ci          # once
//   node compare.mjs [--seed 1] [--accounts 3] [--space-steps 200] -- <command that starts the server>
//
// The server is started with the environment spec/PDS.md and
// spec/ACCOUNTS.md list, PDS_PLC_URL the alpha's directory,
// PDS_RECOVERY_DID_KEY the alpha's recovery key and PDS_LEXICON_AUTHORITY_DID
// the third PDS's account, and with no accounts.
// The reference is held to every check too, which checks the check.

import { spawn } from 'node:child_process'
import { mkdtempSync, openSync } from 'node:fs'
import { createServer } from 'node:net'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { isDeepStrictEqual } from 'node:util'
import { ECDH } from 'node:crypto'
import { Secp256k1Keypair } from '@atproto/crypto'
import { TestNetworkNoAppView } from '@atproto/dev-env'
import { base58btc } from 'multiformats/bases/base58'
import { p256Point } from './lib/spec.mjs'
import { spaceRepo } from './repo.mjs'
import { spaceExport } from './export.mjs'
import { checkVectors } from './vectors.mjs'
import { checkSpaceCredentials } from './credentials.mjs'
import { checkPolicies } from './policies.mjs'
import { checkSpaceSync } from './sync.mjs'
import { checkSsrf } from './ssrf.mjs'
import { checkSpaceScopes, hostDeclarations } from './scopes.mjs'
import { checkIssuerKeys } from './issuers.mjs'

// ---- arguments and the one random source ------------------------------------------

const dash = process.argv.indexOf('--')
const opts = process.argv.slice(2, dash === -1 ? undefined : dash)
const command = dash === -1 ? [] : process.argv.slice(dash + 1)
const opt = (name, fallback) => { const i = opts.indexOf(name); return i === -1 ? fallback : Number(opts[i + 1]) }
const SEED = opt('--seed', 1)
const ACCOUNTS = opt('--accounts', 3)
const SPACE_STEPS = opt('--space-steps', 200)
if (!command.length) {
  console.error('usage: node compare.mjs [--seed N] [--accounts N] [--space-steps N] -- <server command...>')
  process.exit(2)
}
let state = SEED >>> 0
const rand = () => { state = (state + 0x6d2b79f5) >>> 0; let t = state; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296 }
const front = () => `sp${Math.floor(rand() * 1e6)}x`

// ---- the processes -----------------------------------------------------------------

const freePort = () => new Promise((ok) => { const s = createServer(); s.listen(0, '127.0.0.1', () => { const { port } = s.address(); s.close(() => ok(port)) }) })
let net, lexicons, serverProc, serverExited, logPath
const counts = {}
const count = (kind) => { counts[kind] = (counts[kind] ?? 0) + 1 }

async function shutdown(code) {
  serverProc?.kill('SIGKILL')
  await lexicons?.pds.close().catch(() => {})
  await net?.close().catch(() => {})
  process.exit(code)
}

async function differ(what, request, theirs, ours, note) {
  console.error(`\nseed ${SEED}: ${what} differs${note ? `: ${note}` : ''}`)
  console.error('request:', JSON.stringify(request, null, 2))
  console.error('reference:', JSON.stringify(theirs, null, 2))
  console.error('server:', JSON.stringify(ours, null, 2))
  if (logPath) console.error(`server log: ${logPath}`)
  await shutdown(1)
}

function startServer(env) {
  serverExited = null
  const log = openSync(logPath, 'a')
  serverProc = spawn(command[0], command.slice(1), { env: { ...process.env, ...env }, stdio: ['ignore', log, log] })
  const self = serverProc
  self.on('exit', (code, signal) => { if (serverProc === self) serverExited = { code, signal } })
}
async function waitReady(url) {
  const started = Date.now()
  for (;;) {
    if (serverExited) { console.error(`the server exited before it was ready (${JSON.stringify(serverExited)}); its log is ${logPath}`); await shutdown(1) }
    try { if ((await fetch(`${url}/xrpc/com.atproto.server.describeServer`)).ok) return } catch {}
    if (Date.now() - started > 30_000) { console.error(`the server did not answer describeServer within 30s; its log is ${logPath}`); await shutdown(1) }
    await new Promise((ok) => setTimeout(ok, 20))
  }
}
async function killServer(signal = 'SIGKILL') {
  const dying = serverProc
  if (!dying || serverExited) return
  const gone = new Promise((ok) => dying.once('exit', ok))
  dying.kill(signal)
  await gone
}
/// Killed, or shut down with `signal` (SIGTERM or SIGINT), and started
/// again on its data with `e`, as a variant of the run needs (ssrf.mjs:
/// SSRF protection on, then off again; issuers.mjs: issuers' keys across a
/// shutdown).
async function restartWith(e, { signal = 'SIGKILL' } = {}) {
  await killServer(signal)
  startServer(e)
  await waitReady(cand.url)
}

// ---- requests and normalization ----------------------------------------------------------

async function xrpc(side, nsid, { params, body, token } = {}) {
  const url = new URL(`${side.url}/xrpc/${nsid}`)
  for (const [k, v] of Object.entries(params ?? {})) url.searchParams.set(k, v)
  const headers = {}
  if (token) headers.authorization = `Bearer ${token}`
  if (body !== undefined) headers['content-type'] = 'application/json'
  const res = await fetch(url, { method: body === undefined ? 'GET' : 'POST', headers, body: body === undefined ? undefined : JSON.stringify(body) })
  const text = await res.text()
  let parsed = null
  try { parsed = text ? JSON.parse(text) : null } catch { parsed = { unparsed: text.slice(0, 200) } }
  return { status: res.status, body: parsed }
}

const accounts = []
/// An answer with what differs between two servers taken out: each
/// account's DID named alike, the side's URL, keys and tokens, and error
/// messages (spec/PDS.md).
function normalize(side, res, extra = []) {
  const names = [...accounts.map((a) => [a.sides[side.name].did, `<did:${a.n}>`]), ...extra]
  const str = (s) => {
    for (const [d, n] of names) if (d) s = s.split(d).join(n)
    for (const u of new Set([side.publicUrl, side.url])) s = s.split(u).join('<url>')
    return s.replace(/did:key:z[1-9A-HJ-NP-Za-km-z]+/g, '<key>')
  }
  const walk = (v, k) => {
    if (typeof v === 'string') return ['accessJwt', 'refreshJwt'].includes(k) ? '<token>' : k === 'publicKeyMultibase' ? '<key>' : str(v)
    if (Array.isArray(v)) return v.map((x) => walk(x))
    if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v).filter(([key]) => !(key === 'message' && 'error' in v)).map(([key, x]) => [key, walk(x, key)]))
    return v
  }
  if (res.status >= 400) return { status: res.status, error: res.body?.error ?? null }
  return { status: res.status, body: walk(res.body) }
}

let ref, cand
async function both(kind, nsid, request) {
  const on = (side) => (typeof request === 'function' ? request(side) : request)
  const [a, b] = await Promise.all([xrpc(ref, nsid, on(ref)), xrpc(cand, nsid, on(cand))])
  const [na, nb] = [normalize(ref, a), normalize(cand, b)]
  if (!isDeepStrictEqual(na, nb)) await differ(nsid, kind, na, nb)
  count(kind)
  return [a, b]
}
/// A check held to both sides: the reference failing it is the harness's to fix.
const fail = (side, what, request, want, got) => differ(`the ${side.name}'s ${what}`, request, want, got, side === ref ? 'the reference fails the check it is held to' : undefined)

// ---- the PLC directory --------------------------------------------------------------------

const plcGet = async (path) => { const r = await fetch(`${net.plc.url}/${path}`); return { status: r.status, body: await r.json().catch(() => null) } }

/// A P-256 did:key of a point on the curve.
const isP256 = (s) => { try { p256Point(s); return true } catch { return false } }
/// The key of a verification method, as a did:key, in either form the
/// directory may render (atproto/did.md): Multikey, or the legacy types.
function vmDidKey(vm) {
  if (!vm) return undefined
  if (vm.type === 'Multikey') return `did:key:${vm.publicKeyMultibase}`
  const [curve, prefix] = vm.type === 'EcdsaSecp256r1VerificationKey2019' ? ['prime256v1', [0x80, 0x24]] : vm.type === 'EcdsaSecp256k1VerificationKey2019' ? ['secp256k1', [0xe7, 0x01]] : []
  if (!curve) return undefined
  const compressed = ECDH.convertKey(Buffer.from(base58btc.decode(vm.publicKeyMultibase)), curve, undefined, undefined, 'compressed')
  return `did:key:${base58btc.encode(Uint8Array.from([...prefix, ...compressed]))}`
}
const vmOf = (doc, did, frag) => doc?.verificationMethod?.find((v) => v.id === `#${frag}` || v.id === `${did}#${frag}`)

// ---- the checks ------------------------------------------------------------------------------

/// The genesis operation the directory holds for `did` on `side`, which must be
/// spec/ACCOUNTS.md's with the KEM key, a P-256 did:key other than the
/// signing key (spec/SPACES.md, "Keys", "The KEM key", "P-256 did:keys");
/// answers its two keys.
async function checkGenesis(side, acct, request) {
  const did = acct.sides[side.name].did
  const log = await plcGet(`${did}/log`)
  if (log.status !== 200 || !Array.isArray(log.body) || log.body.length !== 1) return fail(side, 'PLC log', request, 'one genesis operation', log)
  const { sig, ...op } = log.body[0]
  const key = op.verificationMethods?.atproto
  const kem = op.verificationMethods?.atproto_kem
  const want = {
    type: 'plc_operation',
    verificationMethods: {
      atproto: typeof key === 'string' && key.startsWith('did:key:zQ3s') ? key : '<the signing key, a secp256k1 did:key>',
      atproto_kem: isP256(kem) && kem !== key ? kem : '<the KEM key, a P-256 did:key other than the signing key>',
    },
    rotationKeys: [side.recoveryKey, side.rotationKey],
    alsoKnownAs: [`at://${acct.handle}`],
    services: { atproto_pds: { type: 'AtprotoPersonalDataServer', endpoint: side.publicUrl } },
    prev: null,
  }
  if (typeof sig !== 'string' || !isDeepStrictEqual(op, want)) await fail(side, 'PLC genesis operation', request, want, { ...op, sig })
  acct.sides[side.name].key = key
  acct.sides[side.name].kem = kem
}

/// The DID document the directory serves for the account must be the one
/// answered, and name the account's KEM key as `#atproto_kem`
/// (spec/SPACES.md, "The KEM key").
async function checkDoc(side, acct, didDoc, what, request) {
  const did = acct.sides[side.name].did
  const doc = await plcGet(did)
  if (doc.status !== 200) return fail(side, what, request, 'the DID registered with the PLC directory', doc)
  if (didDoc !== undefined && !isDeepStrictEqual(didDoc, doc.body)) await fail(side, what, request, { didDoc: doc.body }, { didDoc })
  const named = vmDidKey(vmOf(doc.body, did, 'atproto_kem'))
  if (named !== acct.sides[side.name].kem) await fail(side, `${what}: the directory's #atproto_kem`, request, acct.sides[side.name].kem, vmOf(doc.body, did, 'atproto_kem') ?? null)
}

/// getRecommendedDidCredentials names the account's two keys, the KEM key
/// the genesis operation's (spec/SPACES.md, "Keys", "The KEM key").
async function checkCredentials(acct, kind) {
  const [a, b] = await both(kind, 'com.atproto.identity.getRecommendedDidCredentials', (side) => ({ token: acct.sides[side.name].token }))
  for (const [side, res] of [[ref, a], [cand, b]]) {
    const vm = res.body?.verificationMethods
    const want = { atproto: acct.sides[side.name].key, atproto_kem: acct.sides[side.name].kem }
    if (!isDeepStrictEqual(vm, want)) await fail(side, `${kind} verificationMethods`, { token: `<token of did:${acct.n}>` }, want, vm ?? res.body)
  }
}

async function createAccount() {
  const f = front()
  const body = { handle: `${f}.test`, email: `${f}@example.com`, password: `pw-${f}` }
  const [a, b] = await Promise.all([ref, cand].map((side) => xrpc(side, 'com.atproto.server.createAccount', { body })))
  const name = `<did:${accounts.length + 1}>`
  const [na, nb] = [normalize(ref, a, [[a.body?.did, name]]), normalize(cand, b, [[b.body?.did, name]])]
  if (!isDeepStrictEqual(na, nb)) await differ('com.atproto.server.createAccount', body, na, nb)
  if (a.status !== 200) await differ('com.atproto.server.createAccount', body, 'an account', na, 'the reference refuses an account the harness means to make')
  count('createAccount')
  const acct = { n: accounts.length + 1, handle: body.handle, password: body.password, sides: { reference: { did: a.body.did, token: a.body.accessJwt, refresh: a.body.refreshJwt }, server: { did: b.body.did, token: b.body.accessJwt, refresh: b.body.refreshJwt } } }
  accounts.push(acct)
  for (const [side, res] of [[ref, a], [cand, b]]) {
    await checkGenesis(side, acct, body)
    await checkDoc(side, acct, res.body.didDoc, 'createAccount didDoc', body)
  }
  await checkCredentials(acct, 'getRecommendedDidCredentials')
  return acct
}

/// describeServer's `did`, `availableUserDomains` and `inviteCodeRequired`
/// compared, and `spacesAlpha: true` on each side (spec/SPACES.md,
/// "describeServer").
async function describeServer() {
  const [a, b] = await Promise.all([ref, cand].map((side) => xrpc(side, 'com.atproto.server.describeServer')))
  const pickOut = (side, res) => { const { did, availableUserDomains, inviteCodeRequired, spacesAlpha } = res.body ?? {}; return normalize(side, { status: res.status, body: { did, availableUserDomains, inviteCodeRequired, spacesAlpha } }) }
  const [na, nb] = [pickOut(ref, a), pickOut(cand, b)]
  if (!isDeepStrictEqual(na, nb)) await differ('com.atproto.server.describeServer', {}, na, nb)
  for (const [side, res] of [[ref, a], [cand, b]]) if (res.body?.spacesAlpha !== true) await fail(side, 'describeServer spacesAlpha', {}, true, res.body?.spacesAlpha ?? null)
  count('describeServer')
}

/// A handle change keeps the KEM key: the operation it posts has every
/// verification method of the one before (spec/SPACES.md, "The KEM key").
async function updateHandle(acct) {
  const handle = `${front()}.test`
  const before = {}
  for (const side of [ref, cand]) before[side.name] = (await plcGet(`${acct.sides[side.name].did}/log`)).body
  await both('updateHandle', 'com.atproto.identity.updateHandle', (side) => ({ token: acct.sides[side.name].token, body: { handle } }))
  acct.handle = handle
  for (const side of [ref, cand]) {
    const log = (await plcGet(`${acct.sides[side.name].did}/log`)).body
    const last = log?.at(-1)
    if (log?.length !== before[side.name].length + 1 || !isDeepStrictEqual(last?.verificationMethods, before[side.name].at(-1).verificationMethods)) await fail(side, 'operation of updateHandle', { handle }, { verificationMethods: before[side.name].at(-1).verificationMethods, operations: before[side.name].length + 1 }, { verificationMethods: last?.verificationMethods, operations: log?.length })
    await checkDoc(side, acct, undefined, 'DID document after updateHandle', { handle })
  }
  await checkCredentials(acct, 'getRecommendedDidCredentials after updateHandle')
}

/// Killed and started again on its data, the server keeps each account's
/// KEM key, and posts nothing to the directory (spec/SPACES.md, "The KEM
/// key").
async function restart(env) {
  const before = {}
  for (const a of accounts) before[a.n] = (await plcGet(`${a.sides.server.did}/log`)).body.length
  await killServer()
  startServer(env)
  await waitReady(cand.url)
  for (const a of accounts) {
    const res = await xrpc(cand, 'com.atproto.identity.getRecommendedDidCredentials', { token: a.sides.server.token })
    if (res.body?.verificationMethods?.atproto_kem !== a.sides.server.kem) await differ('getRecommendedDidCredentials after a restart', { account: `<did:${a.n}>` }, a.sides.server.kem, res.body?.verificationMethods ?? res.body, 'the KEM key must survive a restart')
    const n = (await plcGet(`${a.sides.server.did}/log`)).body.length
    if (n !== before[a.n]) await differ('the directory after a restart', { account: `<did:${a.n}>` }, `${before[a.n]} operations`, `${n} operations`, 'a restart posts nothing')
  }
  count('restart')
}

// ---- the run -------------------------------------------------------------------------------

const vectors = await checkVectors().catch((e) => { console.error(e.message); process.exit(1) })
console.error(`all ${vectors} vectors agree with the reference and the spec`)

// A second alpha PDS holds the peers of the spaces checks (repo.mjs,
// credentials.mjs, sync.mjs, policies.mjs).
net = await TestNetworkNoAppView.create({ extraPdses: 1, pds: { hostname: 'localhost', rateLimitsEnabled: false } })
// The lexicon authority both sides resolve space types from (scopes.mjs).
lexicons = await hostDeclarations(net.plc.url)
net.pds.ctx.cfg.lexicon.didAuthority = lexicons.did
const recoveryKey = net.pds.ctx.cfg.identity.recoveryDidKey
const port = await freePort()
const dataDir = mkdtempSync(join(tmpdir(), 'pds-spaces-'))
logPath = join(dataDir, 'server.log')
const rotation = await Secp256k1Keypair.create({ exportable: true })
const env = {
  PDS_PORT: String(port),
  PDS_DATA_DIR: dataDir,
  PDS_HOSTNAME: 'localhost',
  // localhost, not an address: the alpha sends no notifyRepoUpdate to a
  // space host whose #atproto_pds names an IP (spec/SPACES-SYNC.md,
  // "Environment").
  PDS_PUBLIC_URL: `http://localhost:${port}`,
  PDS_HANDLE_DOMAINS: '.test,.example',
  PDS_PLC_URL: net.plc.url,
  PDS_PLC_ROTATION_KEY_HEX: Buffer.from(await rotation.export()).toString('hex'),
  PDS_RECOVERY_DID_KEY: recoveryKey,
  // Every host the server calls in this run is http on localhost, as the
  // alpha runs with no SSRF protection (spec/SPACES-SYNC.md, PROXY.md).
  PDS_DISABLE_SSRF_PROTECTION: 'true',
  // The admin, to take accounts down (export.mjs, policies.mjs; LIFECYCLE.md).
  PDS_ADMIN_PASSWORD: 'spaces-admin',
  // The run's lexicon authority (scopes.mjs, spec/OAUTH-PERMISSION-SETS.md).
  PDS_LEXICON_AUTHORITY_DID: lexicons.did,
}
ref = { name: 'reference', url: net.pds.url, publicUrl: net.pds.ctx.cfg.service.publicUrl, recoveryKey, rotationKey: net.pds.ctx.plcRotationKey.did() }
cand = { name: 'server', url: `http://127.0.0.1:${port}`, publicUrl: env.PDS_PUBLIC_URL, recoveryKey, rotationKey: rotation.did() }
startServer(env)
await waitReady(cand.url)

await describeServer()
for (let i = 0; i < ACCOUNTS; i++) await createAccount()
for (const a of accounts) if (rand() < 0.7) await updateHandle(a)
const repo = spaceRepo({ net, ref, cand, accounts, rand, front, normalize, differ, fail, count })
const exported = spaceExport({ net, ref, cand, accounts, rand, normalize, differ, fail, count, createAccount, refPds: net.pds, env }, repo.internals)
await repo.run(SPACE_STEPS, exported)
const afterRestart = []
await checkSpaceCredentials({ net, ref, cand, differ, count, front, afterRestart })
// Last before the restart: its retries are judged after it.
await checkSpaceSync({ net, ref, cand, accounts, createAccount, normalize, differ, fail, count, rand, front, afterRestart })
await restart(env)
for (const a of accounts) await checkCredentials(a, 'getRecommendedDidCredentials after a restart')
await repo.afterRestart()
for (const check of afterRestart) await check()
await describeServer()
await checkPolicies({ ref, cand, peer: net.extraPdses[0], plcUrl: net.plc.url, refPds: net.pds, rand, front, accounts, normalize, differ, fail, count, createAccount, env })
await exported.statuses()
// The OAuth space: permissions, with the declarations the lexicon authority
// publishes (scopes.mjs, spec/OAUTH-SCOPES.md, "Spaces").
await checkSpaceScopes({ ref, cand, accounts, createAccount, rand, differ, count })
// Last: the guard, with the server started again with SSRF protection on,
// and then as before (ssrf.mjs, spec/SPACES-SYNC.md); and issuers' keys,
// with a short PDS_DID_CACHE_SECS, and then as before (issuers.mjs,
// spec/SPACES-CREDENTIALS.md).
await checkSsrf({ net, cand, env, restartWith, fail, count, front, rand })
await checkIssuerKeys({ cand, env, restartWith, fail, count, front })

console.error(`\nall checks agree (seed ${SEED}), ${accounts.length} accounts`)
for (const [kind, n] of Object.entries(counts).sort()) console.error(`  ${kind.padEnd(56)} ${String(n).padStart(5)}`)
await shutdown(0)