niranzwp 0.7.3 → 0.8.0

package/README.md

@@ -36,12 +36,14 @@ UAE Stories -- UAE's first people centric magazine
   https://uaestories.com
   Tier 1 (app passwords): yes
   Tier 2 (abilities):     yes
+  MCP endpoint:           yes
+  OAuth server:           yes
   namespaces: 38
 
-$ niranzwp probe niranz.dev
-error [server_unreachable]: https://niranz.dev did not return a WordPress
-REST API (HTTP 200, got HTML). Either it is not WordPress, or /wp-json/
-is disabled or blocked.
+$ niranzwp probe example.com
+error [not_wordpress]: https://example.com did not return a WordPress REST
+API (HTTP 200, got HTML). Either it is not WordPress, or /wp-json/ is
+disabled or blocked.
 ```
 
 Tier 2 is deliberately **not** tied to one plugin. Any provider that registers
@@ -49,6 +51,12 @@ abilities through the core API works — Novamira, your own plugin, anything els
 
 ## Install
 
+```sh
+curl -fsSL https://niranz.dev/install.sh | sh
+```
+
+or, if you would rather not pipe a script to a shell:
+
 ```sh
 npm install -g niranzwp
 ```
@@ -62,16 +70,68 @@ Requires Node 22+. No runtime dependencies.
 WordPress redirects back to a temporary loopback listener with the credential.
 Nothing is typed or pasted, and no password crosses a third party.
 
-Credentials go to the **macOS Keychain** where available, otherwise to a
-`0600` file under `~/.config/niranzwp`. Profile metadata (site URL, username)
-lives in `~/.config/niranzwp/profiles.json`; passwords never do.
+Where a site runs an OAuth server, `niranzwp` uses it instead — dynamic client
+registration, PKCE, the device grant, and rotating refresh tokens.
+
+Credentials go to the strongest store the machine offers:
+
+| | |
+|---|---|
+| macOS | Keychain |
+| Linux | libsecret — GNOME Keyring or KWallet, via `secret-tool` |
+| Windows | DPAPI, scoped to your Windows account |
+| otherwise | a `0600` file, and `niranzwp sites` tells you so |
+
+No secret is ever passed as a command-line argument, because process arguments
+are visible to `ps`.
+
+Profile metadata (site URL, username) lives in
+`~/.config/niranzwp/profiles.json`; secrets never do.
+
+`niranzwp auth logout <profile>` revokes the credential on the site and removes
+the local copy. Pass `--local` to keep it on the site.
+
+## Commands
+
+```
+auth login|status|logout      connect, inspect, disconnect
+probe <url>                   what a site supports, before connecting
+doctor                        check every connected site
 
-`niranzwp auth logout <profile>` removes the local copy. Revoke the password
-itself under **Users → Profile → Application Passwords** in WordPress.
+post|page  list|get|create|update|delete
+media      list [--missing-alt] | set-alt <id> "<text>"
+user       list
+settings   get|set <key> <value>
+
+seo   audit | missing <field>
+geo   check | llms-txt [--write]
+
+discover | describe <ability> | run <ability> [--input '<json>']
+mcp   servers|tools|call
+```
+
+Anything that writes needs `--yes`. Anything that reads does not.
+
+`--json` on any command gives machine-readable output — including on failure,
+so a pipeline can branch on the error rather than parse a message.
+
+## Tests
+
+```sh
+NIRANZWP_TEST_SITE=<profile> npm test
+```
+
+51 tests. They run the real binary as a subprocess against a real WordPress
+site and assert on exit codes and printed output, because that is where the
+bugs were. Point them at a throwaway install: the write tests create and delete
+their own content and restore any setting they touch.
 
 ## Status
 
-Early. Tier 1 auth, `probe`, `post list`, `discover`, and `run` work today.
+Usable. Everything in the command list above works and is covered by tests.
+
+Not done yet: no OAuth *server* — that lives in a companion plugin and is not
+written, so MCP clients still authenticate with an application password.
 
 ## License
 

package/bin/niranzwp.js

@@ -10,8 +10,53 @@ import { normalizeSite, probe, whoami, listPosts, listAbilities, runAbility, des
 	listItems, getItem, createItem, updateItem, deleteItem, getSettings, updateSettings, totalOf,
 	introspectAppPassword, revokeAppPassword, WpError, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_OUTPUT } from '../lib/wp.js';
 import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// Read the version from package.json rather than restating it here, where it
+// had already drifted a release behind what npm was publishing.
+const VERSION = JSON.parse(
+	readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')
+).version;
+
+/**
+ * Coerce a command-line string to the type the site already stores for that
+ * key. Everything arrives as a string from argv, and WordPress rejects a
+ * string where its schema wants an integer or a boolean.
+ */
+function coerceLike(raw, sample) {
+	if (typeof sample === 'number') {
+		const n = Number(raw);
+		if (!Number.isFinite(n)) {
+			throw new CliError('invalid_input', `"${raw}" is not a number, and this setting holds one.`);
+		}
+		return n;
+	}
+	if (typeof sample === 'boolean') {
+		if (/^(true|1|yes|on)$/i.test(raw)) return true;
+		if (/^(false|0|no|off)$/i.test(raw)) return false;
+		throw new CliError('invalid_input', `"${raw}" is not a boolean. Use true or false.`);
+	}
+	return raw;
+}
 
-const VERSION = '0.6.0';
+/**
+ * WordPress stores option strings HTML-encoded, so a value written as
+ * "UAE's" reads back as "UAE's". Compare decoded, or every write looks
+ * like it was rejected and every re-write of the same value looks like a
+ * no-op failure.
+ */
+function decodeEntities(v) {
+	if (typeof v !== 'string') return v;
+	return v
+		.replace(/&#(\d+);/g, (_, d) => String.fromCharCode(Number(d)))
+		.replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCharCode(parseInt(h, 16)))
+		.replace(/"/g, '"')
+		.replace(/&lt;/g, '<')
+		.replace(/&gt;/g, '>')
+		.replace(/&amp;/g, '&');
+}
+
+const same = (a, b) => JSON.stringify(decodeEntities(a)) === JSON.stringify(decodeEntities(b));
 
 const USAGE = `NiranzWP CLI v${VERSION} -- a CLI for WordPress
 Built by Niranjan -- https://niranz.dev
@@ -78,7 +123,9 @@ function parseArgs(argv) {
 }
 
 function die(msg, code = 1) {
-	console.error(`error: ${msg}`);
+	// Usage errors go through here too, and they must respect --json for the
+	// same reason the top-level handler does.
+	console.error(process.argv.includes('--json') ? JSON.stringify({ error: 'usage_error', message: msg, hint: null }) : `error: ${msg}`);
 	process.exit(code);
 }
 
@@ -170,8 +217,19 @@ async function main() {
 	}
 
 	if (cmd === 'auth' && sub === 'status') {
-		const all = listProfiles();
+		let all = listProfiles();
 		if (!all.length) { console.log('No sites connected.'); return; }
+		// --site was accepted and then ignored here, unlike every other
+		// command, so "auth status --site x" quietly reported on all of them.
+		if (typeof flags.site === 'string') {
+			const only = all.filter((p) => p.name === flags.site);
+			if (!only.length) {
+				throw new CliError('not_found', `No connected site named "${flags.site}".`, {
+					hint: `Known: ${all.map((p) => p.name).join(', ')}`,
+				});
+			}
+			all = only;
+		}
 		for (const p of all) {
 			const full = getProfile(p.name);
 			let who = 'credential missing';
@@ -243,7 +301,7 @@ async function main() {
 	if (cmd === 'probe') {
 		const url = sub;
 		if (!url) die('usage: niranzwp probe <url>');
-		const info = await probe(normalizeSite(url));
+		const info = await probe(normalizeSite(url), { timeout: Number(flags.timeout) || undefined });
 		out(flags, info, (i) => {
 			console.log(`${i.name} -- ${i.description || ''}`);
 			console.log(`  ${i.home}`);
@@ -367,13 +425,20 @@ async function main() {
 
 		if (sub === 'set-alt') {
 			const [id, ...words] = rest;
+			// Same as settings: "" clears wrong alt text, which the old
+			// truthiness check made unreachable.
+			if (!id || words.length === 0) die('usage: niranzwp media set-alt <id> "<alt text>"   (pass "" to clear)');
 			const alt = words.join(' ');
-			if (!id || !alt) die('usage: niranzwp media set-alt <id> "<alt text>"');
 			if (flags.yes !== true) {
 				throw new CliError('approval_required', `This sets alt text on media ${id} at ${p.siteUrl}.`, { hint: 'Re-run with --yes.' });
 			}
 			const r = await updateItem(p, 'media', id, { alt_text: alt }, reqOpts(flags));
-			console.log(`media ${r.id} alt set to: ${r.alt_text}`);
+			if ((r.alt_text ?? '') !== alt) {
+				throw new CliError('write_rejected', `${p.siteUrl} accepted the request but media ${id} alt is ${JSON.stringify(r.alt_text ?? '')}.`, {
+					hint: 'An SEO or media plugin may be filtering alt text on save.',
+				});
+			}
+			console.log(alt === '' ? `media ${r.id} alt cleared` : `media ${r.id} alt set to: ${r.alt_text}`);
 			return;
 		}
 
@@ -410,14 +475,39 @@ async function main() {
 
 		if (sub === 'set') {
 			const [key, ...words] = rest;
-			const value = words.join(' ');
-			if (!key || !value) die('usage: niranzwp settings set <key> <value>');
+			// words.length rather than a truthiness check: "" is a legitimate
+			// value, and refusing it made it impossible to clear a setting.
+			if (!key || words.length === 0) die('usage: niranzwp settings set <key> <value>   (pass "" to clear)');
+
+			const current = await getSettings(p, reqOpts(flags));
+			if (!(key in current)) {
+				const near = Object.keys(current).filter((k) => k.includes(key) || key.includes(k)).slice(0, 3);
+				throw new CliError('invalid_input', `"${key}" is not a setting exposed by ${p.siteUrl}.`, {
+					hint: near.length
+						? `Did you mean ${near.map((k) => `"${k}"`).join(' or ')}? Run "niranzwp settings get" for the full list.`
+						: 'Run "niranzwp settings get" for the writable keys. WordPress ignores unknown keys silently, so this would otherwise have looked like it worked.',
+				});
+			}
+
 			if (flags.yes !== true) {
 				throw new CliError('approval_required', `This changes "${key}" on ${p.siteUrl}.`, { hint: 'Re-run with --yes.' });
 			}
-			const before = (await getSettings(p, reqOpts(flags)))[key];
-			const after = await updateSettings(p, { [key]: value }, reqOpts(flags));
-			console.log(`${key}\n  before: ${JSON.stringify(before)}\n  after:  ${JSON.stringify(after[key])}`);
+
+			const before = current[key];
+			const wanted = coerceLike(words.join(' '), before);
+			const after = (await updateSettings(p, { [key]: wanted }, reqOpts(flags)))[key];
+
+			// A 200 does not mean the value landed. What matters is whether it
+			// moved at all -- WordPress sanitises on save (an apostrophe comes
+			// back as &#039;), so an exact match is the wrong test.
+			if (same(after, before) && !same(wanted, before)) {
+				throw new CliError('write_rejected', `${p.siteUrl} accepted the request but "${key}" is still ${JSON.stringify(after)}.`, {
+					hint: 'The setting may be filtered, read-only, or locked by a plugin or wp-config constant.',
+				});
+			}
+
+			console.log(`${key}\n  before: ${JSON.stringify(before)}\n  after:  ${JSON.stringify(after)}`);
+			if (!same(after, wanted)) console.log('  note:   the site sanitised the value on save');
 			return;
 		}
 
@@ -692,14 +782,34 @@ async function main() {
 	process.exit(1);
 }
 
+// --json is a contract: everything this process writes must be parseable,
+// failures included. Printing "error [x]: ..." under --json broke any script
+// that piped the output to jq.
+const wantsJson = process.argv.includes('--json');
+
 main().catch((e) => {
 	if (e instanceof CliError) {
-		console.error(`error [${e.code}]: ${e.message}`);
-		if (e.hint) console.error(`hint: ${e.hint}`);
+		if (wantsJson) {
+			console.error(JSON.stringify(e.toJSON()));
+		} else {
+			console.error(`error [${e.code}]: ${e.message}`);
+			if (e.hint) console.error(`hint: ${e.hint}`);
+		}
 		process.exit(e.exitCode);
 	}
+
 	if (e instanceof WpError) {
-		die(`${e.message}${e.code ? ` [${e.code}]` : ''}${e.status ? ` (HTTP ${e.status})` : ''}`);
+		const message = `${e.message}${e.code ? ` [${e.code}]` : ''}${e.status ? ` (HTTP ${e.status})` : ''}`;
+		if (wantsJson) {
+			console.error(JSON.stringify({ error: e.code ?? 'wp_error', message: e.message, status: e.status ?? null }));
+			process.exit(2);
+		}
+		die(message);
+	}
+
+	if (wantsJson) {
+		console.error(JSON.stringify({ error: 'unexpected', message: e.message, hint: null }));
+		process.exit(1);
 	}
 	die(e.message);
 });

package/lib/errors.js

@@ -16,6 +16,11 @@ export const EXIT = {
 export const CODES = {
 	usage_error: EXIT.GENERIC,
 	not_found: EXIT.GENERIC,
+	invalid_input: EXIT.GENERIC,
+	// The site returned 200 but the change did not stick. WordPress drops
+	// unknown or unwritable keys without complaining, so this has to be caught
+	// by reading the value back rather than by trusting the status code.
+	write_rejected: EXIT.GENERIC,
 
 	server_unreachable: EXIT.SERVER,
 	not_wordpress: EXIT.SERVER,

package/lib/http.js

@@ -0,0 +1,27 @@
+import { CliError } from './errors.js';
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * fetch() with a deadline.
+ *
+ * Node's fetch has no default timeout, so a site that accepts the connection
+ * and then stops responding hangs the CLI forever. Every network call goes
+ * through here.
+ */
+export async function fetchWithTimeout(url, options = {}, timeout = DEFAULT_TIMEOUT_MS) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeout);
+	try {
+		return await fetch(url, { ...options, signal: controller.signal });
+	} catch (e) {
+		if ('AbortError' === e.name) {
+			throw new CliError('timeout', `${url} did not respond within ${timeout}ms.`, {
+				hint: 'Raise it with --timeout <ms>, or check whether the host is up.',
+			});
+		}
+		throw e;
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/lib/mcp.js

@@ -8,13 +8,14 @@
 // scoped to an MCP endpoint rather than the core REST run route.
 
 import { CliError } from './errors.js';
+import { fetchWithTimeout } from './http.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`, {
+	const res = await fetchWithTimeout(`${siteUrl}/wp-json/mcp`, {
 		headers: { Accept: 'application/json', 'User-Agent': UA },
 	});
 	if (!res.ok) return [];

package/lib/oauth.js

@@ -10,6 +10,7 @@
 
 import { createHash, randomBytes } from 'node:crypto';
 import { WpError } from './wp.js';
+import { fetchWithTimeout } from './http.js';
 
 const UA = 'niranzwp';
 
@@ -31,7 +32,7 @@ async function postForm(url, params, { timeout = 30_000 } = {}) {
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), timeout);
 	try {
-		const res = await fetch(url, {
+		const res = await fetchWithTimeout(url, {
 			method: 'POST',
 			headers: {
 				'Content-Type': 'application/x-www-form-urlencoded',
@@ -54,7 +55,7 @@ async function postJson(url, body, { timeout = 30_000 } = {}) {
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), timeout);
 	try {
-		const res = await fetch(url, {
+		const res = await fetchWithTimeout(url, {
 			method: 'POST',
 			headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': UA },
 			body: JSON.stringify(body),
@@ -72,7 +73,7 @@ async function postJson(url, body, { timeout = 30_000 } = {}) {
 /** 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`, {
+		const res = await fetchWithTimeout(`${siteUrl}/.well-known/oauth-authorization-server`, {
 			headers: { Accept: 'application/json', 'User-Agent': UA },
 		});
 		if (!res.ok) return null;

package/lib/store.js

@@ -4,7 +4,11 @@ import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 
 // Profiles (which sites exist, who we are on each) live in a plain JSON file.
-// Passwords never do -- they go to the OS keychain where available.
+// Secrets never do -- they go to the OS credential store where there is one.
+//
+// No secret is ever passed as a command-line argument. Process arguments are
+// visible to `ps`, so a password handed to the keychain helper on argv is
+// readable by anything that looks at the process list while it runs.
 
 const DIR = join(homedir(), '.config', 'niranzwp');
 const PROFILES = join(DIR, 'profiles.json');
@@ -24,40 +28,168 @@ function writeProfiles(all) {
 	writeFileSync(PROFILES, JSON.stringify(all, null, 2), { mode: 0o600 });
 }
 
-const useKeychain = () => platform() === 'darwin';
-
-function keychainSet(account, secret) {
-	execFileSync('security', [
-		'add-generic-password',
-		'-a', account,
-		'-s', SERVICE,
-		'-w', secret,
-		'-U', // update if it already exists
-	]);
-}
+const account = (name) => `${SERVICE}:${name}`;
+const secretsPath = () => join(DIR, 'secrets.json');
 
-function keychainGet(account) {
+function has(bin, args = ['--version']) {
 	try {
-		return execFileSync('security', [
-			'find-generic-password', '-a', account, '-s', SERVICE, '-w',
-		], { encoding: 'utf8' }).trim();
-	} catch {
-		return null;
+		execFileSync(bin, args, { stdio: 'ignore' });
+		return true;
+	} catch (e) {
+		// A binary that exists but exits non-zero still counts as present;
+		// only "not found" means the backend is unavailable.
+		return 'ENOENT' !== e.code;
 	}
 }
 
-function keychainDelete(account) {
-	try {
-		execFileSync('security', [
-			'delete-generic-password', '-a', account, '-s', SERVICE,
-		], { stdio: 'ignore' });
-	} catch { /* nothing stored */ }
-}
+/* ------------------------------------------------------------------ macOS */
 
-// Fallback for non-macOS: a 0600 file. Less safe than a keychain, so we say so.
-const secretsPath = () => join(DIR, 'secrets.json');
+// `security -w` prints a hex dump instead of the value whenever the stored
+// password is not plain ASCII, which silently corrupted any secret containing
+// non-Latin characters. Storing base64 keeps what goes in ASCII, so what comes
+// back is always the value. The tag distinguishes new entries from ones
+// written before this, which are still plain.
+const B64 = 'b64:';
+
+/**
+ * `security -i` reads its commands from stdin, which is the only way to hand
+ * it a password without putting the password in argv.
+ */
+const macKeychain = {
+	name: 'macOS Keychain',
+	available: () => 'darwin' === platform() && has('security', ['-h']),
+
+	set(acct, secret) {
+		const payload = B64 + Buffer.from(String(secret), 'utf8').toString('base64');
+		execFileSync('security', ['-i'], {
+			input: `add-generic-password -a "${acct}" -s "${SERVICE}" -w "${payload}" -U\n`,
+			stdio: ['pipe', 'ignore', 'pipe'],
+		});
+	},
+
+	get(acct) {
+		let raw;
+		try {
+			raw = execFileSync('security', ['find-generic-password', '-a', acct, '-s', SERVICE, '-w'], {
+				encoding: 'utf8',
+			}).trim();
+		} catch {
+			return null;
+		}
+		if (raw.startsWith(B64)) {
+			return Buffer.from(raw.slice(B64.length), 'base64').toString('utf8');
+		}
+		// Written before the base64 tag. If security hex-dumped it, decode
+		// that; otherwise it is the value as stored.
+		if (/^([0-9a-f]{2})+$/.test(raw) && raw.length >= 8) {
+			return Buffer.from(raw, 'hex').toString('utf8');
+		}
+		return raw;
+	},
+
+	del(acct) {
+		try {
+			execFileSync('security', ['delete-generic-password', '-a', acct, '-s', SERVICE], { stdio: 'ignore' });
+		} catch { /* nothing stored */ }
+	},
+};
+
+/* ------------------------------------------------------------------ Linux */
+
+/**
+ * libsecret's secret-tool, which fronts GNOME Keyring and KWallet. It reads
+ * the secret from stdin by design, so nothing lands in argv.
+ */
+const libsecret = {
+	name: 'libsecret (GNOME Keyring / KWallet)',
+	available: () => 'linux' === platform() && has('secret-tool', ['--version']),
+
+	set(acct, secret) {
+		execFileSync('secret-tool', ['store', '--label', `niranzwp: ${acct}`, 'service', SERVICE, 'account', acct], {
+			input: secret,
+			stdio: ['pipe', 'ignore', 'pipe'],
+		});
+	},
+
+	get(acct) {
+		try {
+			const out = execFileSync('secret-tool', ['lookup', 'service', SERVICE, 'account', acct], { encoding: 'utf8' });
+			// secret-tool returns the value with no trailing newline of its
+			// own, but a stored value may legitimately end in whitespace.
+			return '' === out ? null : out;
+		} catch {
+			return null;
+		}
+	},
 
-function fileSecrets() {
+	del(acct) {
+		try {
+			execFileSync('secret-tool', ['clear', 'service', SERVICE, 'account', acct], { stdio: 'ignore' });
+		} catch { /* nothing stored */ }
+	},
+};
+
+/* ---------------------------------------------------------------- Windows */
+
+/**
+ * DPAPI through PowerShell. The ciphertext is bound to the Windows user
+ * account, so the file alone is useless to anyone else on the machine.
+ *
+ * Windows Credential Manager would be the closer analogue, but `cmdkey`
+ * cannot read a stored password back out, and anything that can needs a
+ * PowerShell module that is not installed by default.
+ */
+const dpapi = {
+	name: 'Windows DPAPI (user-scoped)',
+	available: () => 'win32' === platform() && has('powershell', ['-NoProfile', '-Command', '$PSVersionTable.PSVersion.Major']),
+
+	// The secret travels through an environment variable rather than argv,
+	// for the same reason macOS uses stdin.
+	run(script, secret) {
+		return execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+			encoding: 'utf8',
+			env: { ...process.env, NIRANZWP_SECRET: secret ?? '' },
+		}).trim();
+	},
+
+	set(acct, secret) {
+		const b64 = this.run(
+			'Add-Type -AssemblyName System.Security;' +
+			'$b=[Text.Encoding]::UTF8.GetBytes($env:NIRANZWP_SECRET);' +
+			"$e=[Security.Cryptography.ProtectedData]::Protect($b,$null,'CurrentUser');" +
+			'[Convert]::ToBase64String($e)',
+			secret
+		);
+		const all = fileBlobs();
+		all[acct] = b64;
+		writeBlobs(all);
+	},
+
+	get(acct) {
+		const b64 = fileBlobs()[acct];
+		if (!b64) return null;
+		try {
+			return this.run(
+				'Add-Type -AssemblyName System.Security;' +
+				`$e=[Convert]::FromBase64String('${b64.replace(/'/g, "''")}');` +
+				"$b=[Security.Cryptography.ProtectedData]::Unprotect($e,$null,'CurrentUser');" +
+				'[Text.Encoding]::UTF8.GetString($b)'
+			);
+		} catch {
+			return null;
+		}
+	},
+
+	del(acct) {
+		const all = fileBlobs();
+		delete all[acct];
+		writeBlobs(all);
+	},
+};
+
+/* --------------------------------------------------------- plain fallback */
+
+function fileBlobs() {
 	if (!existsSync(secretsPath())) return {};
 	try {
 		return JSON.parse(readFileSync(secretsPath(), 'utf8'));
@@ -66,26 +198,54 @@ function fileSecrets() {
 	}
 }
 
-function account(name) {
-	return `${SERVICE}:${name}`;
+function writeBlobs(all) {
+	mkdirSync(DIR, { recursive: true, mode: 0o700 });
+	writeFileSync(secretsPath(), JSON.stringify(all), { mode: 0o600 });
 }
 
-function putSecret(name, value) {
-	if (useKeychain()) {
-		keychainSet(account(name), value);
-		return;
+/** Last resort: a 0600 file. Weaker than any keychain, and `storageKind` says so. */
+const plainFile = {
+	name: `file (${secretsPath()}, mode 0600)`,
+	available: () => true,
+	set(acct, secret) {
+		const all = fileBlobs();
+		all[acct] = secret;
+		writeBlobs(all);
+	},
+	get(acct) {
+		return fileBlobs()[acct] ?? null;
+	},
+	del(acct) {
+		const all = fileBlobs();
+		delete all[acct];
+		writeBlobs(all);
+	},
+};
+
+let cached = null;
+
+/** Pick the strongest backend this machine actually offers. */
+function backend() {
+	if (cached) return cached;
+	for (const b of [macKeychain, libsecret, dpapi, plainFile]) {
+		try {
+			if (b.available()) {
+				cached = b;
+				return b;
+			}
+		} catch { /* try the next one */ }
 	}
-	const s = fileSecrets();
-	s[name] = value;
-	mkdirSync(DIR, { recursive: true, mode: 0o700 });
-	writeFileSync(secretsPath(), JSON.stringify(s), { mode: 0o600 });
+	cached = plainFile;
+	return cached;
 }
 
+/* -------------------------------------------------------------- profiles */
+
 export function saveProfile(name, { siteUrl, user, password }) {
 	const all = readProfiles();
 	all[name] = { siteUrl, user, auth: 'app-password', createdAt: new Date().toISOString() };
 	writeProfiles(all);
-	putSecret(name, password);
+	backend().set(account(name), password);
 }
 
 /**
@@ -104,7 +264,7 @@ export function saveOAuthProfile(name, { siteUrl, user, clientId, tokens }) {
 		createdAt: all[name]?.createdAt ?? new Date().toISOString(),
 	};
 	writeProfiles(all);
-	putSecret(name, JSON.stringify(tokens));
+	backend().set(account(name), JSON.stringify(tokens));
 }
 
 /** Replace just the token pair after a refresh, keeping profile metadata. */
@@ -114,19 +274,29 @@ export function updateTokens(name, tokens) {
 		all[name].expiresAt = tokens.expiresAt;
 		writeProfiles(all);
 	}
-	putSecret(name, JSON.stringify(tokens));
+	backend().set(account(name), JSON.stringify(tokens));
 }
 
 export function getProfile(name) {
 	const p = readProfiles()[name];
 	if (!p) return null;
-	const secret = useKeychain() ? keychainGet(account(name)) : fileSecrets()[name];
-	if (!secret) return null;
+
+	let secret = backend().get(account(name));
+
+	// Profiles written before the backend was pluggable keyed the fallback
+	// file by bare profile name. Read those, and migrate on the next write.
+	if (null === secret) {
+		const legacy = fileBlobs()[name];
+		if (undefined === legacy) return null;
+		secret = legacy;
+	}
 
 	if ('oauth' === p.auth) {
-		let tokens = null;
-		try { tokens = JSON.parse(secret); } catch { return null; }
-		return { name, ...p, tokens };
+		try {
+			return { name, ...p, tokens: JSON.parse(secret) };
+		} catch {
+			return null;
+		}
 	}
 	return { name, ...p, password: secret };
 }
@@ -140,17 +310,18 @@ export function deleteProfile(name) {
 	delete all[name];
 	writeProfiles(all);
 
-	if (useKeychain()) {
-		keychainDelete(account(name));
-	} else {
-		const s = fileSecrets();
-		delete s[name];
-		if (existsSync(secretsPath())) writeFileSync(secretsPath(), JSON.stringify(s), { mode: 0o600 });
+	backend().del(account(name));
+
+	// Clear any legacy entry too, so logout really removes the credential.
+	const blobs = fileBlobs();
+	if (name in blobs) {
+		delete blobs[name];
+		writeBlobs(blobs);
 	}
 }
 
 export function storageKind() {
-	return useKeychain() ? 'macOS Keychain' : `file (${secretsPath()}, mode 0600)`;
+	return backend().name;
 }
 
 export function configDir() {

package/lib/wp.js

@@ -1,4 +1,5 @@
-import { CliError, fromRest } from './errors.js';
+import { CliError, fromRest } from "./errors.js";
+import { fetchWithTimeout } from "./http.js";
 import { discover, refresh as refreshTokens, isExpired } from './oauth.js';
 import { updateTokens } from './store.js';
 import * as cache from './cache.js';
@@ -74,7 +75,13 @@ export async function request(profile, path, {
 	raw = false,
 	timeout = DEFAULT_TIMEOUT_MS,
 	maxOutput = DEFAULT_MAX_OUTPUT,
+	_retried = false,
 } = {}) {
+	// Rotate an expiring OAuth token before spending it. This used to be
+	// written and never called, so every OAuth profile simply started failing
+	// with 401 once its access token aged out.
+	profile = await ensureFresh(profile);
+
 	const url = new URL(path.startsWith('http') ? path : `${profile.siteUrl}/wp-json${path}`);
 	for (const [k, v] of Object.entries(query || {})) {
 		if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
@@ -117,6 +124,16 @@ export async function request(profile, path, {
 	const data = await parse(res, maxOutput);
 
 	if (!res.ok) {
+		// A token can be revoked server-side before it expires on the clock, so
+		// isExpired() will not have caught it. Refresh once and retry.
+		if (401 === res.status && 'oauth' === profile.auth && profile.tokens?.refreshToken && !_retried) {
+			const meta = await discover(profile.siteUrl);
+			if (meta) {
+				const tokens = await refreshTokens(meta, profile.clientId, profile.tokens.refreshToken);
+				updateTokens(profile.name, tokens);
+				return request({ ...profile, tokens }, path, { method, body, query, raw, timeout, maxOutput, _retried: true });
+			}
+		}
 		throw fromRest(res.status, data);
 	}
 
@@ -124,12 +141,12 @@ export async function request(profile, path, {
 }
 
 // Unauthenticated probe: what does this site actually support?
-export async function probe(siteUrl) {
+export async function probe(siteUrl, { timeout = DEFAULT_TIMEOUT_MS } = {}) {
 	let res;
 	try {
-		res = await fetch(`${siteUrl}/wp-json/`, {
+		res = await fetchWithTimeout(`${siteUrl}/wp-json/`, {
 			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
-		});
+		}, timeout);
 	} catch (e) {
 		throw reachError(siteUrl, e);
 	}
@@ -162,9 +179,9 @@ export async function probe(siteUrl) {
 
 	let oauth = null;
 	try {
-		const r = await fetch(`${siteUrl}/.well-known/oauth-authorization-server`, {
+		const r = await fetchWithTimeout(`${siteUrl}/.well-known/oauth-authorization-server`, {
 			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
-		});
+		}, timeout);
 		if (r.ok) oauth = await r.json();
 	} catch { /* not every site has one */ }
 
@@ -279,7 +296,7 @@ export function isReadOnly(ability) {
  */
 export async function contract(siteUrl, endpoint = '/wp-json/mcp/novamira-oauth') {
 	try {
-		const res = await fetch(`${siteUrl}/.well-known/oauth-protected-resource${endpoint}`, {
+		const res = await fetchWithTimeout(`${siteUrl}/.well-known/oauth-protected-resource${endpoint}`, {
 			headers: { Accept: 'application/json', 'User-Agent': 'niranzwp' },
 		});
 		if (!res.ok) return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niranzwp",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "A CLI for WordPress. Works on any site via Application Passwords, and unlocks Abilities where a site provides them.",
   "type": "module",
   "bin": {
@@ -28,6 +28,9 @@
     "seo",
     "site-management"
   ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "engines": {
     "node": ">=22"
   },