chadtmiller.com/monolith
An atproto PDS
0
0
// Calls through a method's MCP tool or CLI command, made from its lexicon as
// spec/COMMANDS.md says, through the admin's reads' and the account's OAuth
// and passkey routes' tools and commands, which that page writes out, and
// through `pds xrpc`, which calls any of them by name; each answered as XRPC
// answers it.
import { spawn } from 'node:child_process'
import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { isDeepStrictEqual } from 'node:util'
import Ajv2020 from 'ajv/dist/2020.js'
import Ajv07 from 'ajv'
import { command } from './args.mjs'
import { chance, pick } from './random.mjs'
import { cand } from './processes.mjs'
import { count, differ } from './report.mjs'
import { accountWithToken, didOf } from './state.mjs'
/// Every method the lexicons in spec/lexicons define, with what
/// spec/COMMANDS.md derives from it: its group and name, its tool (for a JSON
/// answer), the tool's title, and its command, and its arguments, typed
/// (spec/COMMANDS.md, "Names", "Which methods").
export const METHODS = (() => {
const root = new URL('../../spec/lexicons/', import.meta.url).pathname
const files = []
const walk = (dir) => {
for (const f of readdirSync(dir)) {
const p = join(dir, f)
if (statSync(p).isDirectory()) walk(p)
else if (f.endsWith('.json')) files.push(p)
}
}
walk(root)
const snake = (s) => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`)
const kebab = (s) => s.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
const out = {}
for (const f of files) {
const lex = JSON.parse(readFileSync(f, 'utf8'))
const main = lex.defs?.main
if (!main || !['query', 'procedure', 'subscription'].includes(main.type)) continue
const segs = lex.id.split('.')
const [group, name] = segs.slice(-2)
const schema = main.type === 'query' ? main.parameters : main.type === 'procedure' ? main.input?.schema : main.parameters
// A method that answers nothing has a tool too, answering `{}`.
const json = !main.output || main.output.encoding === 'application/json'
out[lex.id] = {
nsid: lex.id,
kind: main.type,
group,
name,
description: main.description,
props: schema?.properties ?? {},
required: schema?.required ?? [],
nullable: schema?.nullable ?? [],
tool: main.type !== 'subscription' && json ? `${group}_${snake(name)}` : null,
title: titleOf(group, kebab(name)),
command: main.type !== 'subscription' ? kebab(name) : null,
flag: (p) => `--${kebab(p)}`,
}
// A method whose input is not JSON, as uploadBlob's, has no tool either.
if (main.input && main.input.encoding !== 'application/json') out[lex.id].tool = null
}
return out
})()
/// A tool's title, from its group and its command's name in kebab case: the
/// name in words, each `-` a space, the first capitalized, then the group in
/// parentheses (spec/COMMANDS.md, "Names").
function titleOf(group, command) {
const words = command.replaceAll('-', ' ')
return `${words[0].toUpperCase()}${words.slice(1)} (${group})`
}
/// Each tool's `readOnlyHint` and `destructiveHint`, as spec/COMMANDS.md,
/// "Hints", gives them, read from that section: its first item names the
/// queries that sign a token, its second the procedures that only add, each
/// named in full or, after one so named, by its last segment alone.
const HINTS = (() => {
const page = readFileSync(new URL('../../spec/COMMANDS.md', import.meta.url), 'utf8')
const section = /\n## Hints\n([\s\S]*?)\n## /.exec(page)?.[1]
const items = section?.split(/\n- /).slice(1) ?? []
if (items.length !== 2) throw new Error('spec/COMMANDS.md, "Hints", has not its two items, of queries and of procedures')
const named = (text, kind) => {
let prefix
const out = new Set()
for (const [, t] of text.matchAll(/`([^`]*)`/g)) {
if (!/^[A-Za-z][\w.]*$/.test(t)) continue
if (t.includes('.')) prefix = t.slice(0, t.lastIndexOf('.'))
else if (!prefix) throw new Error(`spec/COMMANDS.md, "Hints", names ${t} before naming a method in full`)
const nsid = t.includes('.') ? t : `${prefix}.${t}`
if (METHODS[nsid]?.kind !== kind) throw new Error(`spec/COMMANDS.md, "Hints", names ${nsid}, which is no ${kind} of the lexicons`)
out.add(nsid)
}
return out
}
return { signs: named(items[0], 'query'), adds: named(items[1], 'procedure') }
})()
/// The annotations method `m`'s tool must have (spec/COMMANDS.md, "Hints").
export function hintsOf(m) {
if (m.kind === 'query') return HINTS.signs.has(m.nsid) ? { readOnlyHint: false, destructiveHint: false } : { readOnlyHint: true }
return { readOnlyHint: false, destructiveHint: !HINTS.adds.has(m.nsid) }
}
/// The tool titles a section of spec/COMMANDS.md gives as code: each title
/// by the rule of "Names" must be among them.
function given(heading) {
const page = readFileSync(new URL('../../spec/COMMANDS.md', import.meta.url), 'utf8')
const section = new RegExp(`\\n## ${heading}\\n([\\s\\S]*?)\\n## `).exec(page)?.[1] ?? ''
return (title) => {
if (!section.replace(/\s*\n\s*/g, ' ').includes(`\`${title}\``)) throw new Error(`spec/COMMANDS.md gives no title ${title} under the heading ${heading}`)
return title
}
}
/// The quoted descriptions of a section of spec/COMMANDS.md, by tool:
/// `- \`tool\`: "…"`, its lines joined.
function described(heading) {
const page = readFileSync(new URL('../../spec/COMMANDS.md', import.meta.url), 'utf8')
const section = new RegExp(`\\n## ${heading}\\n([\\s\\S]*?)\\n## `).exec(page)?.[1] ?? ''
return (tool) => {
const d = new RegExp(`- \`${tool}\`: "([^"]*)"`).exec(section)?.[1]
if (!d) throw new Error(`spec/COMMANDS.md gives no description of ${tool} under the heading ${heading}`)
return d.replace(/\s*\n\s*/g, ' ')
}
}
/// A flag, from an argument's name in camel case.
const flagOf = (p) => `--${p.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`
/// The admin's reads' tools and commands, which no lexicon makes, as
/// spec/COMMANDS.md, "The admin's reads", gives them: each with its route,
/// its arguments as its `inputSchema` types them, its title, and its
/// description, read from that page.
export const ADMIN_READS = (() => {
const description = described('The admin\'s reads')
const title = given('The admin\'s reads')
const flag = flagOf
return [
{
route: '_logs', tool: 'admin_logs', command: 'logs', title: title(titleOf('admin', 'logs')), description: description('admin_logs'), flag,
props: { trace: { type: 'string' }, msg: { type: 'string' }, method: { type: 'string' }, level: { type: 'string', enum: ['debug', 'info', 'warn', 'error'] }, minMs: { type: 'integer', minimum: 0 }, limit: { type: 'integer', minimum: 1, maximum: 500 } },
},
{ route: '_stats', tool: 'admin_stats', command: 'stats', title: title(titleOf('admin', 'stats')), description: description('admin_stats'), flag, props: {} },
]
})()
/// The account's own routes' tools and commands, which no lexicon makes, as
/// a section of spec/COMMANDS.md, `heading`, gives them for the group
/// `group`: each `[route, tool, command, props, hints]` with its HTTP
/// method (`GET` for one with no arguments), its arguments as its
/// `inputSchema` types them, all required, its hints, its title, and its
/// description, read from that page.
function ownRoutes(heading, group, rows) {
const description = described(heading)
const title = given(heading)
return rows.map(([route, tool, command, props, hints]) => {
const reads = Object.keys(props).length === 0
return { route, tool, command, group, method: reads ? 'GET' : 'POST', hints, props, required: Object.keys(props), title: title(titleOf(group, command)), description: description(tool), flag: flagOf }
})
}
const READS = { readOnlyHint: true }
const ENDS = { readOnlyHint: false, destructiveHint: true }
const ADDS = { readOnlyHint: false, destructiveHint: false }
/// The account's OAuth routes' tools and commands (spec/OAUTH-ACCOUNT.md),
/// as spec/COMMANDS.md, "The account's OAuth sessions", gives them, in its
/// order.
export const OAUTH_ROUTES = ownRoutes('The account\'s OAuth sessions', 'oauth', [
['_oauthSessions', 'oauth_sessions', 'sessions', {}, READS],
['_oauthRevokeSession', 'oauth_revoke_session', 'revoke-session', { id: { type: 'string' } }, ENDS],
['_oauthDevices', 'oauth_devices', 'devices', {}, READS],
['_oauthRevokeDevice', 'oauth_revoke_device', 'revoke-device', { id: { type: 'string' } }, ENDS],
])
/// The account's passkey routes' tools and commands (spec/PASSKEYS.md), as
/// spec/COMMANDS.md, "The account's passkeys", gives them, in its order:
/// `name` bounded as that page bounds it.
export const PASSKEY_ROUTES = ownRoutes('The account\'s passkeys', 'passkey', [
['_passkeyList', 'passkey_list', 'list', {}, READS],
['_passkeyAdd', 'passkey_add', 'add', { name: { type: 'string', minLength: 1, maxLength: 64 } }, ADDS],
['_passkeyRemove', 'passkey_remove', 'remove', { id: { type: 'string' } }, ENDS],
])
/// The arguments that name the account, which a tool or command may leave out.
export const ACCOUNT_ARGS = ['repo', 'did']
export const MCP_VERSION = '2026-07-28'
/// The legacy revisions the endpoint serves beside the modern one, each with
/// an `initialize` handshake (spec/COMMANDS.md, "The MCP endpoint").
export const MCP_LEGACY = ['2025-11-25', '2025-06-18']
/// Each revision's schema, by version: `2025-06-18`'s is JSON Schema
/// draft-07, under `definitions`; the others are 2020-12, under `$defs`.
const SCHEMAS = (() => {
const load = (p) => JSON.parse(readFileSync(new URL(`../../spec/mcp/${p}`, import.meta.url), 'utf8'))
const modern = new Ajv2020({ strict: false, validateFormats: false, allErrors: true })
modern.addSchema(load('schema.json'), MCP_VERSION)
modern.addSchema(load('legacy/2025-11-25/schema.json'), '2025-11-25')
const draft07 = new Ajv07({ strict: false, validateFormats: false, allErrors: true })
draft07.addSchema(load('legacy/2025-06-18/schema.json'), '2025-06-18')
return { [MCP_VERSION]: [modern, '$defs'], '2025-11-25': [modern, '$defs'], '2025-06-18': [draft07, 'definitions'] }
})()
/// A definition of revision `era`'s schema, by name.
export const mcpShape = (era, name) => {
const [ajv, defs] = SCHEMAS[era]
return ajv.getSchema(`${era}#/${defs}/${name}`)
}
let mcpId = 0
/// A POST to the server's MCP endpoint with `headers` and `body` as they are;
/// answers its status, headers, and the JSON-RPC messages in its body.
export async function mcpPost(body, headers) {
let res, text
try {
res = await fetch(`${cand.url}/mcp`, { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...headers }, body: JSON.stringify(body) })
text = await res.text()
} catch (err) {
return { http: 0, failed: err.message }
}
if (!text) return { http: res.status, headers: res.headers, messages: [] }
try {
const messages = (res.headers.get('content-type') ?? '').startsWith('text/event-stream')
? text.split(/\r?\n\r?\n/).map((ev) => ev.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trimStart()).join('\n')).filter(Boolean).map((d) => JSON.parse(d))
: [JSON.parse(text)]
return { http: res.status, headers: res.headers, messages }
} catch {
return { http: res.status, failed: `an answer that is not JSON-RPC: ${text.slice(0, 200)}` }
}
}
/// One JSON-RPC request to the server's MCP endpoint, in `era`: the modern
/// revision, with its `_meta` and headers, or a legacy one, named in the
/// `MCP-Protocol-Version` header alone, as a client does after `initialize`.
/// `token` is sent as a bearer token, or `authorization` as the whole
/// header, as the admin's `Basic`. Every message it answers must be valid
/// against its era's schema, as `shape` names it.
export async function mcpRpc(method, params, token, shape, era = MCP_VERSION, authorization) {
const id = ++mcpId
const modern = era === MCP_VERSION
const meta = {
'io.modelcontextprotocol/protocolVersion': MCP_VERSION,
'io.modelcontextprotocol/clientCapabilities': {},
'io.modelcontextprotocol/clientInfo': { name: 'monolith-harness', version: '0' },
}
const body = { jsonrpc: '2.0', id, method, params: modern ? { ...params, _meta: meta } : params }
const headers = { 'mcp-protocol-version': era }
if (modern) headers['mcp-method'] = method
if (modern && params.name !== undefined) headers['mcp-name'] = params.name
if (authorization) headers.authorization = authorization
else if (token) headers.authorization = `Bearer ${token}`
const r = await mcpPost(body, headers)
if (r.failed) return r
const message = r.messages.find((m) => m.id === id)
if (!message) return { http: r.http, headers: r.headers, failed: `no answer with id ${id}: ${JSON.stringify(r.messages).slice(0, 200)}` }
for (const m of r.messages) {
const name = m === message && m.result ? shape : 'JSONRPCMessage'
const check = mcpShape(era, name)
if (!check(m === message && m.result ? m.result : m)) await differ(`MCP ${method}${modern ? '' : ` (${era})`}`, params, `a message valid against the ${era} schema (${name})`, { message: m, errors: check.errors.slice(0, 5) })
}
return { http: r.http, headers: r.headers, message }
}
/// XRPC error names and their statuses, to set a tool's error, which has no
/// status, beside the reference's XRPC one.
const ERROR_STATUS = {
InvalidRequest: 400, RecordNotFound: 400, InvalidSwap: 400, RepoNotFound: 400, InvalidToken: 400, ExpiredToken: 400,
InvalidHandle: 400, UnsupportedDomain: 400, HandleNotAvailable: 400, InvalidInviteCode: 400,
HandleNotFound: 400, BlobNotFound: 400, InvalidMimeType: 400, InvalidSize: 400, PayloadTooLarge: 413, UpstreamFailure: 502,
AuthMissing: 401, AuthenticationRequired: 401, AccountNotFound: 403, InternalServerError: 500, MethodNotImplemented: 501,
InvalidEmail: 400, TokenRequired: 400, AuthFactorTokenRequired: 401, LogNotKept: 404,
}
/// The method's arguments, as a tool or command takes them: with a token,
/// sometimes without the required `repo` or `did` that names the token's
/// account, which then names it (spec/COMMANDS.md, "Arguments").
function argsOf(m, params, body, token) {
const args = { ...(params ?? body ?? {}) }
const acct = accountWithToken(cand, token)
for (const k of ACCOUNT_ARGS) if (acct && m.required.includes(k) && (args[k] === acct.handle || args[k] === didOf(cand, acct)) && chance(0.5)) delete args[k]
for (const k of Object.keys(args)) if (args[k] === undefined) delete args[k]
return args
}
/// A call through the method's MCP tool, answered in `xrpcHttp`'s form, or
/// null if the method has no tool: the token passed as XRPC takes it, and
/// the answer, or the error, as `structuredContent` and again as text
/// (spec/COMMANDS.md, "Auth", "Answers").
export async function viaTool(nsid, { params, body, token, raw }) {
const m = METHODS[nsid]
if (!m?.tool || raw) return null
const args = argsOf(m, params, body, token)
count(`via tool ${m.tool}`, true)
// Either era, at random: modern, or one of the legacy revisions.
const era = chance(0.5) ? MCP_VERSION : pick(MCP_LEGACY)
const r = await mcpRpc('tools/call', { name: m.tool, arguments: args }, token, 'CallToolResult', era)
// With no token, a method that needs an account is the endpoint's sign-in
// challenge (spec/OAUTH-MCP.md, "Tokens at the MCP endpoint"): what XRPC
// answers 401 AuthMissing.
if (!token && r.http === 401 && /resource_metadata="/.test(r.headers?.get('www-authenticate') ?? '')) return { status: 401, body: { error: 'AuthMissing', message: 'the sign-in challenge' } }
return toolAnswer(m.tool, args, r)
}
/// The answer `r` (mcpRpc's) to a call of `tool` with `args`, in
/// `xrpcHttp`'s form: the answer, or the error, as `structuredContent` and
/// again as text (spec/COMMANDS.md, "Answers").
async function toolAnswer(tool, args, r) {
if (r.failed) return { status: 0, body: { error: r.failed } }
if (r.message.error) return { status: 0, body: { error: `JSON-RPC ${r.message.error.code}` } }
const result = r.message.result
const out = result.structuredContent
const text = result.content?.find((c) => c.type === 'text')?.text
let parsedText
try {
parsedText = JSON.parse(text)
} catch {}
if (!isDeepStrictEqual(parsedText, out)) await differ(`tool ${tool}`, args, 'the structuredContent again, as JSON in a text block', { structuredContent: out, text })
if (result.isError) {
const { error, message, ...rest } = out ?? {}
if (typeof error !== 'string' || typeof message !== 'string' || Object.keys(rest).length) await differ(`tool ${tool}`, args, '{error, message} for a tool error', out)
return { status: ERROR_STATUS[error] ?? 0, body: { error, message } }
}
return { status: 200, body: out }
}
/// A call through an admin's read's tool (`ADMIN_READS`) in `era`, with
/// `authorization` as the whole header, or none, answered in `xrpcHttp`'s
/// form: with no auth, a tool error as `_logs` and `_stats` answer it, never
/// the sign-in challenge (spec/COMMANDS.md, "The admin's reads";
/// spec/OAUTH-MCP.md, "Tokens at the MCP endpoint").
export async function viaAdminTool(read, args, authorization, era = MCP_VERSION) {
count(`via tool ${read.tool} (${era})`, true)
const r = await mcpRpc('tools/call', { name: read.tool, arguments: args }, undefined, 'CallToolResult', era, authorization)
return toolAnswer(read.tool, args, r)
}
/// A call through one of the account's own routes' tools (`OAUTH_ROUTES`,
/// `PASSKEY_ROUTES`) in `era`, with `token` as a bearer token, or none,
/// answered in `xrpcHttp`'s form. With none, the endpoint's sign-in
/// challenge, as its route answers `401 AuthMissing`, and so `401
/// AuthMissing`; a tool error in its place is a difference
/// (spec/COMMANDS.md, "The account's OAuth sessions", "The account's
/// passkeys"; spec/OAUTH-MCP.md, "Tokens at the MCP endpoint").
export async function viaRouteTool(route, args, token, era = MCP_VERSION) {
count(`via tool ${route.tool} (${era})`, true)
const r = await mcpRpc('tools/call', { name: route.tool, arguments: args }, token, 'CallToolResult', era)
if (token) return toolAnswer(route.tool, args, r)
if (r.http !== 401 || !/resource_metadata="/.test(r.headers?.get('www-authenticate') ?? '')) {
await differ(`tool ${route.tool}`, { args, token: 'none', era }, 'HTTP 401 with the sign-in challenge, as its route answers 401 AuthMissing', r.failed ? { http: r.http, failed: r.failed } : { http: r.http, message: r.message }, 'spec/OAUTH-MCP.md, "Tokens at the MCP endpoint"')
}
return { status: 401, body: { error: 'AuthMissing', message: 'the sign-in challenge' } }
}
/// The `pds` binary, whose `serve` is the server and whose other commands
/// are the CLI (spec/COMMANDS.md, "One binary").
const PDS = command[0]
/// Run the CLI with `argv`, sending `stdin` if given, with `PDS_URL` (the
/// server's, or `url`), the call's token as `PDS_TOKEN`, and the admin's
/// password as `PDS_ADMIN_PASSWORD` if given (spec/COMMANDS.md, "Auth").
/// Answers its exit status and what it wrote.
export function runCli(argv, { token, stdin, adminPassword, url } = {}) {
return new Promise((ok) => {
const env = { ...process.env, PDS_URL: url ?? cand.url }
// The CLI's credentials are the call's alone, never the shell's.
delete env.PDS_TOKEN
delete env.PDS_ADMIN_PASSWORD
if (token) env.PDS_TOKEN = token
if (adminPassword) env.PDS_ADMIN_PASSWORD = adminPassword
const p = spawn(PDS, argv, { env, stdio: ['pipe', 'pipe', 'pipe'] })
const out = []
let err = ''
p.stdout.on('data', (d) => out.push(d))
p.stderr.on('data', (d) => (err += d))
p.on('error', (e) => ok({ code: -1, stdout: Buffer.alloc(0), stderr: String(e) }))
p.on('close', (code) => ok({ code, stdout: Buffer.concat(out), stderr: err }))
// A command that exits without reading its input closes the pipe first.
p.stdin.on('error', () => {})
p.stdin.end(stdin ?? '')
})
}
/// The CLI arguments of method `m` with `args`, and the standard input to
/// send, or null if an argument cannot be a flag: a `null`, one the method
/// does not take, one not of its flag's type, or text that starts with `-`,
/// which a command could take for a flag (spec/COMMANDS.md, "Arguments").
export function commandLine(m, args) {
const fits = (type, v) => (type === 'string' ? typeof v === 'string' && !v.startsWith('-') : type === 'integer' ? Number.isInteger(v) : type === 'boolean' ? typeof v === 'boolean' : true)
if (Object.entries(args).some(([k, v]) => v === null || !m.props[k] || !fits(m.props[k].type, v))) return null
const argv = [m.group, m.command]
let stdin
for (const [k, v] of Object.entries(args)) {
const type = m.props[k].type
if (type === 'string') argv.push(m.flag(k), v)
else if (type === 'integer') argv.push(m.flag(k), String(v))
else if (type === 'boolean') v && chance(0.5) ? argv.push(m.flag(k)) : argv.push(m.flag(k), String(v))
else if (stdin === undefined && chance(0.3)) {
stdin = JSON.stringify(v)
argv.push(m.flag(k), '-')
} else argv.push(m.flag(k), JSON.stringify(v))
}
return { argv, stdin }
}
/// A call through the method's CLI command, answered in `xrpcHttp`'s form,
/// or null if the method has no command, an argument cannot be a flag, or
/// one it requires is missing, which is a usage error, not a call. Its
/// answer is one line of JSON, an error `{status, error, message}` with exit
/// status 1 (spec/COMMANDS.md, "Answers").
export async function viaCommand(nsid, { params, body, token, raw }) {
const m = METHODS[nsid]
if (!m?.command) return null
const args = argsOf(m, params, body, token)
if (m.required.some((k) => !(k in args) && !(token && ACCOUNT_ARGS.includes(k)))) return null
const line = commandLine(m, args)
if (!line) return null
const { argv, stdin } = line
count(`via command ${m.group} ${m.command}`, true)
const r = await runCli(argv, { token, stdin })
return commandAnswer(`pds ${m.group} ${m.command}`, { argv: ['pds', ...argv], stdin }, r, raw)
}
/// What the CLI wrote, `r` (runCli's), for `request`, in `xrpcHttp`'s
/// form: one line of JSON, an error `{status, error, message}` with exit
/// status 1; `raw`, the bytes it wrote (spec/COMMANDS.md, "Answers").
async function commandAnswer(command, request, r, raw) {
if (r.code === 0 && raw) return { status: 200, bytes: new Uint8Array(r.stdout) }
if (r.code === 3) return { status: 0, body: { error: 'unreachable' } }
if (r.code !== 0 && r.code !== 1) await differ(`command ${command}`, request, 'exit status 0 or 1', { code: r.code, stderr: r.stderr.slice(0, 500) })
const lines = r.stdout.toString('utf8').split('\n').filter(Boolean)
let parsed
try {
if (lines.length !== 1) throw new Error()
parsed = JSON.parse(lines[0])
} catch {
await differ(`command ${command}`, request, 'one line of JSON on standard output', r.stdout.toString('utf8').slice(0, 500))
}
if (r.code === 0) return { status: 200, body: parsed }
const { status, error, message, ...rest } = parsed
if (typeof status !== 'number' || typeof error !== 'string' || typeof message !== 'string' || Object.keys(rest).length) await differ(`command ${command}`, request, '{status, error, message} for an error', parsed)
return { status, body: { error, message } }
}
/// A call through an admin's read's command (`ADMIN_READS`), `pds admin
/// <command>` with a flag for each of `args`, with `token` or the admin's
/// `adminPassword` or neither, answered in `xrpcHttp`'s form
/// (spec/COMMANDS.md, "The admin's reads", "Auth", "Answers").
export async function viaAdminCommand(read, args, { token, adminPassword } = {}) {
const argv = ['admin', read.command, ...Object.entries(args).flatMap(([k, v]) => [read.flag(k), String(v)])]
count(`via command admin ${read.command}`, true)
const r = await runCli(argv, { token, adminPassword })
return commandAnswer(`pds admin ${read.command}`, { argv: ['pds', ...argv], auth: token ? 'a token' : adminPassword ? 'the admin\'s' : 'none' }, r)
}
/// A call through one of the account's own routes' commands
/// (`OAUTH_ROUTES`, `PASSKEY_ROUTES`), `pds <group> <command>` with a flag
/// for each of `args`, with `token` or none, answered in `xrpcHttp`'s form
/// (spec/COMMANDS.md, "The account's OAuth sessions", "The account's
/// passkeys", "Auth", "Answers").
export async function viaRouteCommand(route, args, { token } = {}) {
const argv = [route.group, route.command, ...Object.entries(args).flatMap(([k, v]) => [route.flag(k), String(v)])]
count(`via command ${route.group} ${route.command}`, true)
const r = await runCli(argv, { token })
return commandAnswer(`pds ${route.group} ${route.command}`, { argv: ['pds', ...argv], auth: token ? 'a token' : 'none' }, r)
}
/// A key `pds xrpc` can take before a separator: not empty, with no `:`,
/// `=` or NUL in it, and not starting with `-` or `@`, which read as other
/// forms (spec/COMMANDS.md, "Any call").
const bareKey = (k) => k !== '' && !/[:=\0]/.test(k) && !/^[-@]/.test(k)
/// The longest argument put on the command line: a body with one longer goes
/// whole in an `@path` file, as some systems bound a single argument.
const ARG_MAX = 30_000
/// `pds xrpc`'s kind of a GET or a POST: `query` or `get`, `procedure` or
/// `post`, in any case (spec/COMMANDS.md, "Any call").
function kindOf(post) {
const w = post ? pick(['procedure', 'post']) : pick(['query', 'get'])
return pick([w, w.toUpperCase(), `${w[0].toUpperCase()}${w.slice(1)}`])
}
let scratch
let files = 0
/// A new file holding `text`, for `pds xrpc`'s `@path`.
export function scratchFile(text) {
scratch ??= mkdtempSync(join(tmpdir(), 'pds-xrpc-'))
const path = join(scratch, `${++files}.json`)
writeFileSync(path, text)
return path
}
/// The arguments of `pds xrpc` for a call of `name` as XRPC makes it, in
/// each of the forms the request allows, drawn at random: each parameter as
/// `k==v`, again for each value of an array; a JSON object body's
/// properties as `k=v` (a string) or `k:=json`, some or all of them in an
/// `@path` file given first; a body that is no object, or any at times, as
/// `-` with a `Content-Type:` header; and `bytes` as `-` with
/// `contentType`. The token sent as the CLI sends it, or at times as an
/// `Authorization:` header, which replaces the CLI's own. Answers `{argv,
/// stdin, token, file, shown}`, or null if a parameter cannot be an argument
/// (spec/COMMANDS.md, "Any call").
export function xrpcLine(name, { params, body, bytes, contentType, token, headers = {} }) {
const post = body !== undefined || bytes !== undefined
const query = []
for (const [k, v] of Object.entries(params ?? {})) {
for (const x of Array.isArray(v) ? v : [v]) {
if (x === undefined) continue
const s = String(x)
if (!bareKey(k) || s.includes('\0') || s.length > ARG_MAX) return null
query.push(`${k}==${s}`)
}
}
const head = Object.entries(headers).map(([k, v]) => `${k}:${v}`)
const ct = pick(['Content-Type', 'content-type'])
const props = []
let stdin
let file
if (bytes !== undefined) {
head.push(`${ct}:${contentType}`)
props.push('-')
stdin = bytes
} else if (body !== undefined) {
const json = JSON.stringify(body)
const object = body !== null && typeof body === 'object' && !Array.isArray(body)
if (!object || chance(0.15)) {
head.push(`${ct}:application/json`)
props.push('-')
stdin = json
} else {
const entries = Object.entries(body).filter(([, v]) => v !== undefined)
const big = json.length > ARG_MAX
const p = chance(0.3) ? 0.6 : 0
const inFile = entries.filter(([k]) => big || !bareKey(k) || chance(p))
if (inFile.length || (!entries.length && chance(0.3))) {
file = scratchFile(JSON.stringify(Object.fromEntries(inFile)))
props.push(`@${file}`)
}
for (const [k, v] of entries) {
if (inFile.some(([f]) => f === k)) continue
props.push(typeof v === 'string' && !v.includes('\0') && chance(0.7) ? `${k}=${v}` : `${k}:=${JSON.stringify(v)}`)
}
}
}
let envToken = token
if (token && chance(0.2)) {
head.push(`Authorization:Bearer ${token}`)
envToken = chance(0.5) ? 'not-a-token' : undefined
}
const rest = chance(0.5) ? [...head, ...query, ...props] : [...query, ...props, ...head]
const argv = ['xrpc', kindOf(post), name, ...rest]
const hide = (s) => (s.startsWith('Authorization:') ? 'Authorization:Bearer <token>' : s)
const shown = ['pds', ...argv.map(hide)]
return { argv, stdin, token: envToken, file, shown }
}
/// A call of `name`, a method or one of the server's own routes, through
/// `pds xrpc`, answered in `xrpcHttp`'s form as a command's is, or null if
/// the request is one it cannot make: a `method` other than its body makes,
/// or a parameter that cannot be an argument. It fills in nothing, so the
/// request goes as it is; `adminPassword` is sent as the CLI sends it
/// (spec/COMMANDS.md, "Any call", "Auth", "Answers").
export async function viaXrpc(name, { params, body, token, raw, method, bytes, contentType, adminPassword, headers } = {}) {
const post = body !== undefined || bytes !== undefined
if (method && method !== (post ? 'POST' : 'GET')) return null
const line = xrpcLine(name, { params, body, bytes, contentType, token, headers })
if (!line) return null
count(`via pds xrpc ${name}`, true)
const fileText = line.file ? readFileSync(line.file, 'utf8') : undefined
const r = await runCli(line.argv, { token: line.token, stdin: line.stdin, adminPassword })
if (line.file) rmSync(line.file, { force: true })
const stdin = line.stdin === undefined ? undefined : typeof line.stdin === 'string' ? line.stdin.slice(0, 300) : `${line.stdin.length} bytes`
const request = { argv: line.shown, stdin, file: fileText?.slice(0, 300), auth: line.token && line.token !== token ? 'PDS_TOKEN not a token, replaced by the header' : undefined }
return commandAnswer(`pds xrpc ${name}`, request, r, raw)
}