niranzwp 0.1.0 → 0.6.1

package/lib/mcp.js

@@ -0,0 +1,185 @@
+// Minimal MCP client over Streamable HTTP.
+//
+// Enough of the protocol to be useful and no more: initialize, tools/list,
+// tools/call. Servers may answer with either JSON or an SSE stream, and may
+// hand back a session id that every later request has to echo.
+//
+// This is what lets NiranzWP run abilities on sites whose OAuth tokens are
+// scoped to an MCP endpoint rather than the core REST run route.
+
+import { CliError } from './errors.js';
+
+const PROTOCOL_VERSION = '2025-06-18';
+const UA = 'niranzwp';
+
+/** List MCP servers a WordPress site exposes. Unauthenticated. */
+export async function listServers(siteUrl) {
+	const res = await fetch(`${siteUrl}/wp-json/mcp`, {
+		headers: { Accept: 'application/json', 'User-Agent': UA },
+	});
+	if (!res.ok) return [];
+
+	const body = await res.json().catch(() => null);
+	const routes = body?.routes ? Object.keys(body.routes) : [];
+
+	// "/mcp" itself is the index, not a server.
+	return routes
+		.filter((r) => r !== '/mcp' && r.startsWith('/mcp/'))
+		.map((r) => ({ route: r, url: `${siteUrl}/wp-json${r}`, name: r.slice('/mcp/'.length) }));
+}
+
+/**
+ * Pick the endpoint a bearer token should talk to. Servers that end in
+ * "-oauth" are the OAuth-protected variants; prefer those when we hold a
+ * token, and fall back to the plain one otherwise.
+ */
+export function pickEndpoint(servers, { oauth = false } = {}) {
+	if (!servers.length) return null;
+	const oauthServer = servers.find((s) => s.name.endsWith('-oauth'));
+	const plain = servers.find((s) => !s.name.endsWith('-oauth'));
+	return (oauth ? oauthServer || plain : plain || oauthServer)?.url ?? servers[0].url;
+}
+
+export class McpClient {
+	constructor(endpoint, { token, basic, timeout = 30_000 } = {}) {
+		this.endpoint = endpoint;
+		this.token = token;
+		this.basic = basic;
+		this.timeout = timeout;
+		this.sessionId = null;
+		this.id = 0;
+		this.serverInfo = null;
+	}
+
+	headers() {
+		const h = {
+			'Content-Type': 'application/json',
+			// Streamable HTTP lets the server answer with either.
+			Accept: 'application/json, text/event-stream',
+			'User-Agent': UA,
+			'MCP-Protocol-Version': PROTOCOL_VERSION,
+		};
+		if (this.token) h.Authorization = `Bearer ${this.token}`;
+		else if (this.basic) h.Authorization = `Basic ${this.basic}`;
+		if (this.sessionId) h['Mcp-Session-Id'] = this.sessionId;
+		return h;
+	}
+
+	async send(method, params, { notification = false } = {}) {
+		const payload = notification
+			? { jsonrpc: '2.0', method, params }
+			: { jsonrpc: '2.0', id: ++this.id, method, params };
+
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.timeout);
+
+		let res;
+		try {
+			res = await fetch(this.endpoint, {
+				method: 'POST',
+				headers: this.headers(),
+				body: JSON.stringify(payload),
+				signal: controller.signal,
+			});
+		} catch (e) {
+			if ('AbortError' === e.name) {
+				throw new CliError('timeout', `MCP request timed out after ${this.timeout}ms.`);
+			}
+			throw new CliError('server_unreachable', `MCP request failed: ${e.message}`);
+		} finally {
+			clearTimeout(timer);
+		}
+
+		// The session id is issued on initialize and must be echoed thereafter.
+		const sid = res.headers.get('mcp-session-id');
+		if (sid) this.sessionId = sid;
+
+		if (401 === res.status) {
+			throw new CliError('auth_required', 'The MCP endpoint rejected this credential.', {
+				hint: 'Run: niranzwp auth login <url>',
+			});
+		}
+		if (403 === res.status) {
+			throw new CliError('insufficient_scope', 'This credential is not accepted by the MCP endpoint.');
+		}
+
+		if (notification) return null;
+
+		const text = await res.text();
+		const msg = parseBody(text);
+
+		if (!msg) {
+			throw new CliError('server_unsupported', `MCP endpoint returned no JSON-RPC message (HTTP ${res.status}).`);
+		}
+		if (msg.error) {
+			throw new CliError('usage_error', `MCP error ${msg.error.code}: ${msg.error.message}`);
+		}
+		return msg.result;
+	}
+
+	async initialize() {
+		const result = await this.send('initialize', {
+			protocolVersion: PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: { name: 'NiranzWP CLI', version: '0.6.0' },
+		});
+		this.serverInfo = result?.serverInfo ?? null;
+		// Per spec the server expects this acknowledgement before real calls.
+		await this.send('notifications/initialized', {}, { notification: true }).catch(() => {});
+		return result;
+	}
+
+	async listTools() {
+		const out = [];
+		let cursor;
+		do {
+			const r = await this.send('tools/list', cursor ? { cursor } : {});
+			out.push(...(r?.tools ?? []));
+			cursor = r?.nextCursor;
+		} while (cursor);
+		return out;
+	}
+
+	async callTool(name, args) {
+		const r = await this.send('tools/call', { name, arguments: args ?? {} });
+
+		// Tool failures come back as a normal result with isError set, not as a
+		// JSON-RPC error, so they have to be surfaced explicitly.
+		if (r?.isError) {
+			throw new CliError('usage_error', textOf(r) || `Tool "${name}" reported an error.`);
+		}
+		return r;
+	}
+}
+
+/** Accept a plain JSON body or an SSE stream carrying one message. */
+function parseBody(text) {
+	if (!text) return null;
+
+	const trimmed = text.trimStart();
+	if (trimmed.startsWith('{')) {
+		try { return JSON.parse(trimmed); } catch { return null; }
+	}
+
+	// SSE: take the last complete data: payload.
+	let last = null;
+	for (const line of text.split('\n')) {
+		if (!line.startsWith('data:')) continue;
+		const chunk = line.slice(5).trim();
+		if (!chunk || '[DONE]' === chunk) continue;
+		try { last = JSON.parse(chunk); } catch { /* keep the previous one */ }
+	}
+	return last;
+}
+
+/** Flatten an MCP tool result into text, preferring structured content. */
+export function textOf(result) {
+	if (!result) return '';
+	if (result.structuredContent !== undefined) {
+		return JSON.stringify(result.structuredContent, null, 2);
+	}
+	const parts = (result.content ?? [])
+		.map((c) => ('text' === c.type ? c.text : `[${c.type}]`))
+		.filter(Boolean);
+	return parts.join('\n');
+}

package/lib/oauth.js

@@ -0,0 +1,196 @@
+// OAuth client for WordPress sites that expose an authorization server.
+//
+// Implements the three specs a modern public client needs:
+//   RFC 7591  dynamic client registration -- no pre-shared client_id
+//   RFC 7636  PKCE with S256 -- mandatory, since there is no client secret
+//   RFC 8628  device authorization grant -- works over SSH and in containers
+//
+// Tokens rotate: every refresh returns a new refresh token and invalidates the
+// old one, so the stored record is replaced atomically or not at all.
+
+import { createHash, randomBytes } from 'node:crypto';
+import { WpError } from './wp.js';
+
+const UA = 'niranzwp';
+
+// Refresh this many ms before the access token actually expires, so a request
+// never races the expiry.
+export const REFRESH_SKEW_MS = 60_000;
+
+function b64url(buf) {
+	return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function pkce() {
+	const verifier = b64url(randomBytes(32));
+	const challenge = b64url(createHash('sha256').update(verifier).digest());
+	return { verifier, challenge };
+}
+
+async function postForm(url, params, { timeout = 30_000 } = {}) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeout);
+	try {
+		const res = await fetch(url, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/x-www-form-urlencoded',
+				Accept: 'application/json',
+				'User-Agent': UA,
+			},
+			body: new URLSearchParams(params).toString(),
+			signal: controller.signal,
+		});
+		const text = await res.text();
+		let json = null;
+		try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON error body */ }
+		return { ok: res.ok, status: res.status, json, text };
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+async function postJson(url, body, { timeout = 30_000 } = {}) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeout);
+	try {
+		const res = await fetch(url, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': UA },
+			body: JSON.stringify(body),
+			signal: controller.signal,
+		});
+		const text = await res.text();
+		let json = null;
+		try { json = text ? JSON.parse(text) : null; } catch { /* ignore */ }
+		return { ok: res.ok, status: res.status, json, text };
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/** Fetch the authorization server metadata, or null if the site has none. */
+export async function discover(siteUrl) {
+	try {
+		const res = await fetch(`${siteUrl}/.well-known/oauth-authorization-server`, {
+			headers: { Accept: 'application/json', 'User-Agent': UA },
+		});
+		if (!res.ok) return null;
+		const meta = await res.json();
+		return meta?.token_endpoint ? meta : null;
+	} catch {
+		return null;
+	}
+}
+
+/** RFC 7591. Public client, so no secret is issued or expected. */
+export async function registerClient(meta, { clientName = 'NiranzWP CLI' } = {}) {
+	if (!meta.registration_endpoint) {
+		throw new WpError('This site does not support dynamic client registration.');
+	}
+
+	const { ok, json, status, text } = await postJson(meta.registration_endpoint, {
+		client_name: clientName,
+		client_uri: 'https://niranz.dev',
+		grant_types: ['authorization_code', 'refresh_token', 'urn:ietf:params:oauth:grant-type:device_code'],
+		response_types: ['code'],
+		token_endpoint_auth_method: 'none',
+		redirect_uris: ['http://127.0.0.1/callback'],
+		scope: (meta.scopes_supported || ['mcp']).join(' '),
+	});
+
+	if (!ok || !json?.client_id) {
+		throw new WpError(`client registration failed (HTTP ${status}): ${json?.error_description || json?.error || text.slice(0, 200)}`);
+	}
+	return json.client_id;
+}
+
+/**
+ * RFC 8628. Returns the code the user types and the page they type it on.
+ * No local listener and no browser is needed on this machine.
+ */
+export async function startDeviceFlow(meta, clientId, { scope } = {}) {
+	if (!meta.device_authorization_endpoint) {
+		throw new WpError('This site does not advertise the device authorization grant.');
+	}
+
+	const { ok, json, status, text } = await postForm(meta.device_authorization_endpoint, {
+		client_id: clientId,
+		scope: scope || (meta.scopes_supported || ['mcp']).join(' '),
+	});
+
+	if (!ok || !json?.device_code) {
+		throw new WpError(`device authorization failed (HTTP ${status}): ${json?.error_description || json?.error || text.slice(0, 200)}`);
+	}
+
+	return {
+		deviceCode: json.device_code,
+		userCode: json.user_code,
+		verificationUri: json.verification_uri_complete || json.verification_uri,
+		interval: Math.max(1, Number(json.interval || 5)),
+		expiresIn: Number(json.expires_in || 600),
+	};
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Poll until the user approves, the code expires, or the deadline passes. */
+export async function pollForToken(meta, clientId, device, { timeoutMs, onPending } = {}) {
+	const deadline = Date.now() + Math.min(device.expiresIn * 1000, timeoutMs ?? device.expiresIn * 1000);
+	let interval = device.interval * 1000;
+
+	while (Date.now() < deadline) {
+		await sleep(interval);
+
+		const { ok, json } = await postForm(meta.token_endpoint, {
+			grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+			device_code: device.deviceCode,
+			client_id: clientId,
+		});
+
+		if (ok && json?.access_token) return toRecord(json);
+
+		const err = json?.error;
+		if ('authorization_pending' === err) { onPending?.(); continue; }
+		// The server is asking us to back off; honour it rather than hammering.
+		if ('slow_down' === err) { interval += 5000; continue; }
+		if ('expired_token' === err) throw new WpError('The device code expired before it was approved.');
+		if ('access_denied' === err) throw new WpError('Authorization was denied.');
+		if (err) throw new WpError(`token request failed: ${json?.error_description || err}`);
+	}
+
+	throw new WpError('Timed out waiting for approval.');
+}
+
+function toRecord(json) {
+	return {
+		accessToken: json.access_token,
+		refreshToken: json.refresh_token || null,
+		scope: json.scope || null,
+		expiresAt: new Date(Date.now() + Number(json.expires_in || 3600) * 1000).toISOString(),
+	};
+}
+
+/**
+ * Exchange a refresh token for a new pair. The old refresh token is consumed,
+ * so the caller must persist the result before making any further request.
+ */
+export async function refresh(meta, clientId, refreshToken) {
+	const { ok, json, status } = await postForm(meta.token_endpoint, {
+		grant_type: 'refresh_token',
+		refresh_token: refreshToken,
+		client_id: clientId,
+	});
+
+	if (!ok || !json?.access_token) {
+		throw new WpError(
+			`refresh failed (HTTP ${status}): ${json?.error_description || json?.error || 'unknown'}. Run: niranzwp auth login <url>`
+		);
+	}
+	return toRecord(json);
+}
+
+export function isExpired(record) {
+	if (!record?.expiresAt) return true;
+	return Date.parse(record.expiresAt) - REFRESH_SKEW_MS <= Date.now();
+}

package/lib/schema.js

@@ -0,0 +1,94 @@
+// A small JSON Schema validator -- only the keywords an ability input_schema
+// actually uses. Catching a bad argument locally beats a round trip and a
+// generic rest_invalid_param back from the site.
+
+const typeOf = (v) => {
+	if (null === v) return 'null';
+	if (Array.isArray(v)) return 'array';
+	if (Number.isInteger(v)) return 'integer';
+	return typeof v;
+};
+
+function matchesType(value, expected) {
+	const actual = typeOf(value);
+	if (Array.isArray(expected)) return expected.some((t) => matchesType(value, t));
+	if ('number' === expected) return 'number' === actual || 'integer' === actual;
+	if ('integer' === expected) return 'integer' === actual;
+	return actual === expected;
+}
+
+/**
+ * @returns {string[]} human-readable errors, empty when the value is valid.
+ */
+export function validate(value, schema, path = '') {
+	const errors = [];
+	if (!schema || 'object' !== typeof schema) return errors;
+
+	const at = path || 'input';
+
+	if (schema.type && !matchesType(value, schema.type)) {
+		errors.push(`${at} must be ${Array.isArray(schema.type) ? schema.type.join(' or ') : schema.type}, got ${typeOf(value)}`);
+		// A wrong type makes every nested check meaningless.
+		return errors;
+	}
+
+	if (schema.enum && !schema.enum.includes(value)) {
+		errors.push(`${at} must be one of: ${schema.enum.join(', ')}`);
+	}
+
+	if ('number' === typeOf(value) || 'integer' === typeOf(value)) {
+		if (schema.minimum !== undefined && value < schema.minimum) {
+			errors.push(`${at} must be >= ${schema.minimum}`);
+		}
+		if (schema.maximum !== undefined && value > schema.maximum) {
+			errors.push(`${at} must be <= ${schema.maximum}`);
+		}
+	}
+
+	if ('string' === typeOf(value)) {
+		if (schema.minLength !== undefined && value.length < schema.minLength) {
+			errors.push(`${at} must be at least ${schema.minLength} characters`);
+		}
+		if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+			errors.push(`${at} must be at most ${schema.maxLength} characters`);
+		}
+	}
+
+	if ('array' === typeOf(value)) {
+		if (schema.minItems !== undefined && value.length < schema.minItems) {
+			errors.push(`${at} must have at least ${schema.minItems} items`);
+		}
+		if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+			errors.push(`${at} must have at most ${schema.maxItems} items`);
+		}
+		if (schema.items) {
+			value.forEach((v, i) => errors.push(...validate(v, schema.items, `${at}[${i}]`)));
+		}
+	}
+
+	if ('object' === typeOf(value)) {
+		for (const key of schema.required ?? []) {
+			if (value[key] === undefined) errors.push(`${at}.${key} is required`);
+		}
+		for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+			if (value[key] !== undefined) {
+				errors.push(...validate(value[key], sub, path ? `${path}.${key}` : key));
+			}
+		}
+	}
+
+	return errors;
+}
+
+/** Fill in defaults the schema declares, so callers can omit common fields. */
+export function applyDefaults(value, schema) {
+	if (!schema?.properties || 'object' !== typeOf(value)) return value;
+
+	const out = { ...value };
+	for (const [key, sub] of Object.entries(schema.properties)) {
+		if (out[key] === undefined && sub.default !== undefined) {
+			out[key] = sub.default;
+		}
+	}
+	return out;
+}

package/lib/store.js

@@ -70,27 +70,65 @@ function account(name) {
 	return `${SERVICE}:${name}`;
 }
 
+function putSecret(name, value) {
+	if (useKeychain()) {
+		keychainSet(account(name), value);
+		return;
+	}
+	const s = fileSecrets();
+	s[name] = value;
+	mkdirSync(DIR, { recursive: true, mode: 0o700 });
+	writeFileSync(secretsPath(), JSON.stringify(s), { mode: 0o600 });
+}
+
 export function saveProfile(name, { siteUrl, user, password }) {
 	const all = readProfiles();
-	all[name] = { siteUrl, user, createdAt: new Date().toISOString() };
+	all[name] = { siteUrl, user, auth: 'app-password', createdAt: new Date().toISOString() };
 	writeProfiles(all);
+	putSecret(name, password);
+}
 
-	if (useKeychain()) {
-		keychainSet(account(name), password);
-	} else {
-		const s = fileSecrets();
-		s[name] = password;
-		mkdirSync(DIR, { recursive: true, mode: 0o700 });
-		writeFileSync(secretsPath(), JSON.stringify(s), { mode: 0o600 });
+/**
+ * OAuth profiles keep the token pair in the same secret slot, serialized.
+ * Refresh rotation consumes the old refresh token, so this must be written
+ * before the new access token is used for anything.
+ */
+export function saveOAuthProfile(name, { siteUrl, user, clientId, tokens }) {
+	const all = readProfiles();
+	all[name] = {
+		siteUrl,
+		user: user ?? null,
+		auth: 'oauth',
+		clientId,
+		expiresAt: tokens.expiresAt,
+		createdAt: all[name]?.createdAt ?? new Date().toISOString(),
+	};
+	writeProfiles(all);
+	putSecret(name, JSON.stringify(tokens));
+}
+
+/** Replace just the token pair after a refresh, keeping profile metadata. */
+export function updateTokens(name, tokens) {
+	const all = readProfiles();
+	if (all[name]) {
+		all[name].expiresAt = tokens.expiresAt;
+		writeProfiles(all);
 	}
+	putSecret(name, JSON.stringify(tokens));
 }
 
 export function getProfile(name) {
 	const p = readProfiles()[name];
 	if (!p) return null;
-	const password = useKeychain() ? keychainGet(account(name)) : fileSecrets()[name];
-	if (!password) return null;
-	return { name, ...p, password };
+	const secret = useKeychain() ? keychainGet(account(name)) : fileSecrets()[name];
+	if (!secret) return null;
+
+	if ('oauth' === p.auth) {
+		let tokens = null;
+		try { tokens = JSON.parse(secret); } catch { return null; }
+		return { name, ...p, tokens };
+	}
+	return { name, ...p, password: secret };
 }
 
 export function listProfiles() {