// A server to try by hand: `pds serve` with a PLC directory of its own in // this process, its mail written to a directory, and what a server on this // machine needs besides; with --seed, accounts to sign in as. It prints what // the CLI and an MCP client need, and runs until Ctrl-C. // // node dev.mjs [--port 2583] [--keep] [--seed] [-- ] // // The server command is ../target/release/pds serve unless given (`just // dev` builds it first). Its data is in target/dev/, made afresh each start; // with --keep it carries on from the last, the PLC directory's operations // replayed from target/dev/plc.json, which each stop writes. No gate runs // this: it is for people. import { spawn } from 'node:child_process' import { randomBytes } from 'node:crypto' import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs' import { join } from 'node:path' import { PlcServer, Database } from '@did-plc/server' const args = process.argv.slice(2) const dash = args.indexOf('--') const opts = dash === -1 ? args : args.slice(0, dash) const flag = (name) => opts.includes(name) const PORT = opts.includes('--port') ? Number(opts[opts.indexOf('--port') + 1]) : 2583 const root = new URL('..', import.meta.url).pathname const command = dash === -1 ? [join(root, 'target/release/pds'), 'serve'] : args.slice(dash + 1) const DEV = join(root, 'target/dev') const PASSWORD = 'password' const ADMIN = 'admin' const SEED = ['alice', 'bob', 'carol'] if (!flag('--keep')) rmSync(DEV, { recursive: true, force: true }) for (const d of ['data', 'mail']) mkdirSync(join(DEV, d), { recursive: true }) if (!existsSync(command[0])) { console.error(`no server at ${command[0]}: run \`just build\`, or give the command after --`) process.exit(2) } // The PLC directory, in memory, with the operations of the last start if // the data is kept. const plc = PlcServer.create({ db: Database.mock(), port: 0 }) const plcPort = (await plc.start()).address().port const plcUrl = `http://127.0.0.1:${plcPort}` const saved = join(DEV, 'plc.json') if (flag('--keep') && existsSync(saved)) { for (const [did, ops] of Object.entries(JSON.parse(readFileSync(saved, 'utf8')))) { for (const op of ops) { const res = await fetch(`${plcUrl}/${did}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(op) }) if (!res.ok) console.error(`the PLC directory refused ${did}'s operation: ${res.status} ${await res.text()}`) } } } // The server's variables: its rotation key kept with its data, as the DIDs // it made name it. const envFile = join(DEV, 'env.json') const kept = flag('--keep') && existsSync(envFile) ? JSON.parse(readFileSync(envFile, 'utf8')) : { PDS_PLC_ROTATION_KEY_HEX: randomBytes(32).toString('hex') } writeFileSync(envFile, `${JSON.stringify(kept, null, 2)}\n`) // localhost, not 127.0.0.1: a browser takes no IP address as a passkey's // RP ID (spec/PASSKEYS.md, "The relying party"). const url = `http://localhost:${PORT}` const env = { ...process.env, ...kept, PDS_PORT: String(PORT), PDS_DATA_DIR: join(DEV, 'data'), PDS_HOSTNAME: 'localhost', PDS_PUBLIC_URL: url, PDS_HANDLE_DOMAINS: '.test', PDS_PLC_URL: plcUrl, PDS_ADMIN_PASSWORD: ADMIN, PDS_DEV_MAIL_DIR: join(DEV, 'mail'), // An AppView of nowhere: what the server serves itself, as preferences, // is served, and what it forwards fails (spec/PROXY.md). PDS_BSKY_APP_VIEW_URL: 'http://127.0.0.1:9', PDS_BSKY_APP_VIEW_DID: 'did:web:appview.invalid', PDS_DISABLE_SSRF_PROTECTION: 'true', } const log = join(DEV, 'server.log') let stopping = false const server = spawn(command[0], command.slice(1), { env, stdio: ['ignore', openSync(log, 'a'), 'inherit'] }) let exited = false server.on('exit', (code, signal) => { exited = true if (!stopping) { console.error(`the server exited (${signal ?? code}); its log is ${log}`) plc.destroy().then(() => process.exit(1)) } }) for (let i = 0; ; i++) { if (await fetch(`${url}/xrpc/com.atproto.server.describeServer`).then((r) => r.ok, () => false)) break if (exited || i === 300) { console.error(`the server did not start; its log is ${log}`) process.exit(1) } await new Promise((ok) => setTimeout(ok, 100)) } const xrpc = (nsid, body) => fetch(`${url}/xrpc/${nsid}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }).then(async (r) => ({ status: r.status, body: await r.json() })) /// Each DID's operations, for the next start with --keep. async function savePlc() { const dids = [] for (let cursor; ; ) { const page = await fetch(`${url}/xrpc/com.atproto.sync.listRepos?limit=1000${cursor ? `&cursor=${cursor}` : ''}`).then((r) => r.json()) dids.push(...page.repos.map((r) => r.did)) if (!page.cursor || !page.repos.length) break cursor = page.cursor } const ops = {} for (const did of dids) { const res = await fetch(`${plcUrl}/${did}/log`) if (res.ok) ops[did] = await res.json() } writeFileSync(saved, `${JSON.stringify(ops, null, 2)}\n`) } const resolves = (handle) => fetch(`${url}/xrpc/com.atproto.identity.resolveHandle?handle=${handle}`).then((r) => r.ok, () => false) if (flag('--seed')) { for (const name of SEED) { if (await resolves(`${name}.test`)) continue const res = await xrpc('com.atproto.server.createAccount', { handle: `${name}.test`, email: `${name}@example.com`, password: PASSWORD }) if (res.status !== 200) console.error(`${name}.test not made: ${JSON.stringify(res.body)}`) } await savePlc() } const seeded = await resolves(`${SEED[0]}.test`) console.log(`Monolith at ${url}, its PLC directory at ${plcUrl}`) console.log(` data ${join(DEV, 'data')}, log ${log}, mail ${join(DEV, 'mail')}`) console.log('\nThe CLI (target/release/pds):\n') console.log(` export PDS_URL=${url} PDS_ADMIN_PASSWORD=${ADMIN}`) if (seeded) { console.log(` export PDS_TOKEN=$(pds server create-session --identifier alice.test --password ${PASSWORD} | jq -r .accessJwt)`) console.log(`\n Accounts: ${SEED.map((n) => `${n}.test`).join(', ')}, each with the password "${PASSWORD}".`) } console.log(`\nMCP: POST ${url}/mcp, protocol 2026-07-28, with Authorization: Bearer .`) console.log('\nCtrl-C stops it; `--keep` next time carries on from here.') for (const signal of ['SIGINT', 'SIGTERM']) { process.on(signal, async () => { if (stopping) return stopping = true if (!exited) { await savePlc().catch((e) => console.error(`the PLC directory's operations were not saved: ${e.message}`)) server.kill('SIGTERM') await new Promise((ok) => (exited ? ok() : server.once('exit', ok))) } await plc.destroy() process.exit(0) }) }