// 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 /// ` 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 ` 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 ' : 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) }