@mokoconsulting/mokomysql-mcp 2.5.4 → 2.6.1

package/source/migrate.ts

@@ -0,0 +1,263 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokomysql-mcp.Migrate
+ * INGROUP: mokomysql-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /source/migrate.ts
+ * BRIEF: Self-heal inline secrets in the MySQL MCP config into file-backed refs.
+ *
+ * No-inline-secrets policy (MokoCLI #1043). Any secret found INLINE in the
+ * on-disk `~/.mcp_mokomysql.json` is migrated to `~/.ssh/tokens/<slug>.token`
+ * and the config is rewritten so the field becomes `file:<path>`.
+ *
+ * mysql-specific: secret files are written as RAW values (NOT JSON). A MySQL
+ * password is an opaque string; `resolveRef()` reads the file verbatim, so a
+ * JSON wrapper would be read back literally and corrupt the credential. This
+ * intentionally diverges from the GitHub/OAuth JSON token-file shape used by
+ * token-based MCPs.
+ */
+
+import { constants as FS } from 'node:fs';
+import { access, chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+
+/** Directory that holds file-backed secrets. */
+function tokensDir(): string {
+	return resolve(homedir(), '.ssh', 'tokens');
+}
+
+/** True when the value is already a `file:<path>` reference (nothing to migrate). */
+function isFileRef(value: unknown): boolean {
+	return typeof value === 'string' && /^file:/.test(value.trim());
+}
+
+/** True when the value is a non-empty inline literal that must be migrated. */
+function isInlineSecret(value: unknown): value is string {
+	return typeof value === 'string' && value.trim() !== '' && !isFileRef(value);
+}
+
+/** Sanitize a slug component to the `[A-Za-z0-9._-]` alphabet. */
+function sanitize(part: string): string {
+	return part.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/** stderr only — stdout is the MCP stdio channel and must never carry logs. */
+function warn(message: string): void {
+	process.stderr.write(`[mokomysql] WARNING: ${message}\n`);
+}
+
+/**
+ * One sensitive field discovered inline on a connection, with the slug its
+ * secret file should take. `field` is the config key to rewrite; `get`/`set`
+ * read and replace the value in the parsed object.
+ */
+interface InlineField {
+	connectionKey: string;
+	/** Human label for warnings, e.g. "prod.password" or "prod.ssl.key". */
+	label: string;
+	slug: string;
+	value: string;
+	/** Replace the inline value with a `file:` ref in the parsed object. */
+	apply(ref: string): void;
+}
+
+/**
+ * Enumerate every inline secret across all connections. The ONLY top-level
+ * connection secret in this config shape is `password`; an inline PEM private
+ * key under `ssl.key` is also a secret value (a key *value*, not a path) and is
+ * migrated too. A `file:` ref or empty value is skipped.
+ */
+function findInlineSecrets(connections: Record<string, unknown>): InlineField[] {
+	const out: InlineField[] = [];
+	for (const [key, raw] of Object.entries(connections)) {
+		if (!raw || typeof raw !== 'object') continue;
+		const conn = raw as Record<string, unknown>;
+		const connSlug = sanitize(key) || 'connection';
+
+		if (isInlineSecret(conn.password)) {
+			out.push({
+				connectionKey: key,
+				label: `${key}.password`,
+				slug: `mysql-${connSlug}-password`,
+				value: conn.password,
+				apply: (ref) => {
+					conn.password = ref;
+				},
+			});
+		}
+
+		const ssl = conn.ssl;
+		if (ssl && typeof ssl === 'object') {
+			const sslRec = ssl as Record<string, unknown>;
+			// An inline PEM private-key *value* (begins with a PEM header) is a
+			// secret; a short reference/path is left alone.
+			if (isInlineSecret(sslRec.key) && /BEGIN[^\n]*PRIVATE KEY/.test(sslRec.key)) {
+				out.push({
+					connectionKey: key,
+					label: `${key}.ssl.key`,
+					slug: `mysql-${connSlug}-ssl-key`,
+					value: sslRec.key,
+					apply: (ref) => {
+						sslRec.key = ref;
+					},
+				});
+			}
+		}
+	}
+	return out;
+}
+
+/** True if the path exists. */
+async function exists(path: string): Promise<boolean> {
+	try {
+		await access(path, FS.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Write the raw secret to `~/.ssh/tokens/<slug>.token` (mode 0600). If the file
+ * already exists it is NOT overwritten — the existing file is reused. Returns
+ * the absolute token path. mysql reads this file RAW, so the content is the
+ * verbatim secret with no trailing newline and no JSON wrapper.
+ */
+async function writeTokenFile(slug: string, secret: string): Promise<string> {
+	const dir = tokensDir();
+	await mkdir(dir, { recursive: true, mode: 0o700 });
+	// Best-effort tighten perms if the dir pre-existed with looser bits.
+	await chmod(dir, 0o700).catch(() => {});
+
+	const tokenPath = resolve(dir, `${slug}.token`);
+	if (await exists(tokenPath)) {
+		warn(`secret file already exists, reusing without overwrite: ${tokenPath}`);
+		return tokenPath;
+	}
+
+	// Atomic: write temp in the same dir, chmod, rename into place.
+	const tmp = `${tokenPath}.tmp-${process.pid}`;
+	await writeFile(tmp, secret, { encoding: 'utf-8', mode: 0o600 });
+	await chmod(tmp, 0o600).catch(() => {});
+	await rename(tmp, tokenPath);
+	return tokenPath;
+}
+
+/** Collapse an absolute path under $HOME back to a portable `~/...` form. */
+function tildeify(absPath: string): string {
+	const home = homedir();
+	if (absPath === home) return '~';
+	const prefix = home.endsWith('/') || home.endsWith('\\') ? home : home + '/';
+	const prefixBack = home.endsWith('/') || home.endsWith('\\') ? home : home + '\\';
+	if (absPath.startsWith(prefix)) return '~/' + absPath.slice(prefix.length).replace(/\\/g, '/');
+	if (absPath.startsWith(prefixBack)) return '~/' + absPath.slice(prefixBack.length).replace(/\\/g, '/');
+	return absPath;
+}
+
+/**
+ * Atomically rewrite the config file with the migrated `file:` refs. Backs the
+ * original up to `<config>.bak` once (only if no `.bak` exists yet). The config
+ * is written mode 0600.
+ */
+async function rewriteConfig(configPath: string, parsed: unknown): Promise<void> {
+	const bak = `${configPath}.bak`;
+	if (!(await exists(bak))) {
+		const original = await readFile(configPath, 'utf-8');
+		await writeFile(bak, original, { encoding: 'utf-8', mode: 0o600 });
+		await chmod(bak, 0o600).catch(() => {});
+	}
+
+	const serialized = JSON.stringify(parsed, null, '\t') + '\n';
+	const tmp = `${configPath}.tmp-${process.pid}`;
+	await writeFile(tmp, serialized, { encoding: 'utf-8', mode: 0o600 });
+	await chmod(tmp, 0o600).catch(() => {});
+	await rename(tmp, configPath);
+	await chmod(configPath, 0o600).catch(() => {});
+}
+
+/**
+ * Self-heal inline secrets in the parsed config, mutating `parsed` in place so
+ * the subsequent `resolveSecretRefs` pass picks up the new `file:` refs.
+ *
+ * Behavior (no-inline-secrets policy):
+ *  - For each inline secret: warn to stderr (never echo the value), write a RAW
+ *    token file under `~/.ssh/tokens/`, and rewrite the config so the field is a
+ *    `file:` ref with the inline literal removed.
+ *  - Existing token files are reused, never overwritten.
+ *  - Config is backed up once to `<config>.bak`; writes are atomic; mode 0600.
+ *  - On ANY error (read-only FS, perms, unwritable config) → warn only and keep
+ *    the inline value for this run. Never throws, never loses the credential.
+ *
+ * Only runs against the real on-disk config path (the resolved
+ * `~/.mcp_mokomysql.json` or its `MYSQL_MCP_CONFIG` override).
+ */
+export async function migrateInlineSecrets(
+	parsed: { connections?: Record<string, unknown> },
+	configPath: string,
+): Promise<void> {
+	try {
+		if (!parsed.connections || typeof parsed.connections !== 'object') return;
+
+		const inline = findInlineSecrets(parsed.connections);
+		if (inline.length === 0) return;
+
+		// Only touch the config if it is the real on-disk file we can read.
+		if (!(await exists(configPath))) {
+			warn(
+				`${inline.length} inline secret(s) found but config path is not a readable file ` +
+					`(${configPath}); leaving inline for this run.`,
+			);
+			return;
+		}
+
+		let migratedAny = false;
+		for (const field of inline) {
+			try {
+				warn(
+					`inline secret detected at ${field.label}; migrating to a file-backed secret ` +
+						`(no-inline-secrets policy, MokoCLI #1043). The value is NOT shown.`,
+				);
+				const tokenPath = await writeTokenFile(field.slug, field.value);
+				field.apply(`file:${tildeify(tokenPath)}`);
+				migratedAny = true;
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				warn(
+					`failed to migrate ${field.label} to a file (${msg}); ` +
+						`keeping the inline value for this run.`,
+				);
+				// Revert any ref we may have set on this field so resolution uses the literal.
+				field.apply(field.value);
+			}
+		}
+
+		if (migratedAny) {
+			try {
+				await rewriteConfig(configPath, parsed);
+				warn(
+					`config rewritten with file-backed secret ref(s): ${configPath} ` +
+						`(backup at ${configPath}.bak).`,
+				);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				warn(
+					`token file(s) written but rewriting the config failed (${msg}); ` +
+						`the config still references the secret value(s) inline. ` +
+						`The file-backed ref(s) are used for this run only.`,
+				);
+			}
+		}
+	} catch (err) {
+		// Absolute backstop — migration must never crash the server.
+		const msg = err instanceof Error ? err.message : String(err);
+		warn(`secret auto-migration aborted (${msg}); continuing with config as-is.`);
+	}
+}
+
+export const __test = { sanitize, isInlineSecret, isFileRef, findInlineSecrets, tildeify };

package/source/secrets.ts

@@ -1,70 +1,78 @@
-/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
- *
- * This file is part of a Moko Consulting project.
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- *
- * FILE INFORMATION
- * DEFGROUP: mokomysql-mcp.Secrets
- * INGROUP: mokomysql-mcp
- * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
- * PATH: /source/secrets.ts
- * BRIEF: Resolve file-backed secret references in a parsed config object.
- */
-
-import { readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
-
-/** Expand a leading "~" to the user's home directory, then resolve to absolute. */
-function expandHome(p: string): string {
-	if (p === '~') return homedir();
-	if (p.startsWith('~/') || p.startsWith('~\\')) {
-		return resolve(homedir(), p.slice(2));
-	}
-	return resolve(p);
-}
-
-/**
- * Resolve a single config string.
- * - "file:<path>" -> the trimmed contents of <path> (a leading "~" expands to $HOME).
- * - anything else  -> returned unchanged, so inline literals keep working.
- *
- * A missing/unreadable file throws (fail loud) — a secret must never silently
- * degrade to the literal "file:..." string.
- */
-async function resolveRef(value: string): Promise<string> {
-	const m = /^file:(.+)$/s.exec(value.trim());
-	if (!m) return value;
-	const path = expandHome(m[1].trim());
-	try {
-		const raw = await readFile(path, 'utf-8');
-		return raw.replace(/\r?\n+$/, '');
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(`Failed to read secret file "${path}" (referenced as "${value}"): ${msg}`);
-	}
-}
-
-/**
- * Recursively resolve every "file:" secret reference in a parsed config object,
- * in place. Lets secrets (tokens, passwords, API keys) live in files such as
- * ~/.ssh/tokens/* instead of inline in the config JSON. Plain values are left
- * untouched, so pre-existing inline configs remain valid.
- */
-export async function resolveSecretRefs(obj: unknown): Promise<void> {
-	if (Array.isArray(obj)) {
-		for (let i = 0; i < obj.length; i++) {
-			const v = obj[i];
-			if (typeof v === 'string') obj[i] = await resolveRef(v);
-			else if (v && typeof v === 'object') await resolveSecretRefs(v);
-		}
-	} else if (obj && typeof obj === 'object') {
-		const rec = obj as Record<string, unknown>;
-		for (const k of Object.keys(rec)) {
-			const v = rec[k];
-			if (typeof v === 'string') rec[k] = await resolveRef(v);
-			else if (v && typeof v === 'object') await resolveSecretRefs(v);
-		}
-	}
-}
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokomysql-mcp.Secrets
+ * INGROUP: mokomysql-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /source/secrets.ts
+ * BRIEF: Resolve file-backed secret references in a parsed config object.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+/** Expand a leading "~" to the user's home directory, then resolve to absolute. */
+function expandHome(p: string): string {
+	if (p === '~') return homedir();
+	if (p.startsWith('~/') || p.startsWith('~\\')) {
+		return resolve(homedir(), p.slice(2));
+	}
+	return resolve(p);
+}
+
+/**
+ * Resolve a single config string.
+ * - "file:<path>" -> the trimmed contents of <path> (a leading "~" expands to $HOME).
+ * - anything else  -> returned unchanged, so inline literals keep working.
+ *
+ * A missing/unreadable file throws (fail loud) — a secret must never silently
+ * degrade to the literal "file:..." string. An empty or whitespace-only file
+ * also throws, so a blank secret file never goes out as an empty value.
+ */
+async function resolveRef(value: string): Promise<string> {
+	const m = /^file:(.+)$/s.exec(value.trim());
+	if (!m) return value;
+	const path = expandHome(m[1].trim());
+	let trimmed: string;
+	try {
+		const raw = await readFile(path, 'utf-8');
+		trimmed = raw.replace(/\r?\n+$/, '');
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to read secret file "${path}" (referenced as "${value}"): ${msg}`);
+	}
+	if (trimmed.trim() === '') {
+		throw new Error(
+			`Secret file "${path}" (referenced as "${value}") is empty or whitespace-only; refusing to use an empty secret value.`
+		);
+	}
+	return trimmed;
+}
+
+/**
+ * Recursively resolve every "file:" secret reference in a parsed config object,
+ * in place. Lets secrets (tokens, passwords, API keys) live in files such as
+ * ~/.ssh/tokens/* instead of inline in the config JSON. Plain values are left
+ * untouched, so pre-existing inline configs remain valid.
+ */
+export async function resolveSecretRefs(obj: unknown): Promise<void> {
+	if (Array.isArray(obj)) {
+		for (let i = 0; i < obj.length; i++) {
+			const v = obj[i];
+			if (typeof v === 'string') obj[i] = await resolveRef(v);
+			else if (v && typeof v === 'object') await resolveSecretRefs(v);
+		}
+	} else if (obj && typeof obj === 'object') {
+		const rec = obj as Record<string, unknown>;
+		for (const k of Object.keys(rec)) {
+			const v = rec[k];
+			if (typeof v === 'string') rec[k] = await resolveRef(v);
+			else if (v && typeof v === 'object') await resolveSecretRefs(v);
+		}
+	}
+}

package/source/state.ts

@@ -1,62 +1,62 @@
-/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
- *
- * This file is part of a Moko Consulting project.
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- *
- * FILE INFORMATION
- * DEFGROUP: mokomysql.State
- * INGROUP: mokomysql
- * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
- * PATH: /source/state.ts
- * BRIEF: Sidecar state store for learned Joomla markers (per host:port/database).
- */
-
-import { readFile, writeFile } from 'node:fs/promises';
-import { getStatePath } from './config.js';
-import type { JoomlaMarker, MySqlState } from './types.js';
-
-let cache: MySqlState | null = null;
-/** Serializes write-through so concurrent setMarker calls can't clobber the file. */
-let writeChain: Promise<void> = Promise.resolve();
-
-/** Stable key for a learned verdict: identifies the physical database target. */
-export function markerKey(host: string, port: number, database: string): string {
-	return `${host}:${port}/${database}`;
-}
-
-/** Load the sidecar once into memory; a missing/corrupt file is an empty store. */
-export async function loadState(): Promise<MySqlState> {
-	if (cache) return cache;
-	try {
-		const parsed = JSON.parse(await readFile(getStatePath(), 'utf-8')) as Partial<MySqlState>;
-		cache = parsed && typeof parsed.markers === 'object' && parsed.markers !== null
-			? { markers: parsed.markers }
-			: { markers: {} };
-	} catch {
-		cache = { markers: {} };
-	}
-	return cache;
-}
-
-export async function getMarker(key: string): Promise<JoomlaMarker | undefined> {
-	return (await loadState()).markers[key];
-}
-
-/**
- * Record a learned verdict and persist it. The write is best-effort: an unwritable
- * sidecar (read-only home, permissions) must not break queries — the in-memory
- * cache still carries the verdict for this process, we just can't remember it next time.
- */
-export async function setMarker(key: string, marker: JoomlaMarker): Promise<void> {
-	const state = await loadState();
-	state.markers[key] = marker;
-	writeChain = writeChain.then(async () => {
-		try {
-			await writeFile(getStatePath(), JSON.stringify(state, null, '\t') + '\n', 'utf-8');
-		} catch (e) {
-			process.stderr.write(`mokomysql: could not write state file ${getStatePath()}: ${e}\n`);
-		}
-	});
-	await writeChain;
-}
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokomysql.State
+ * INGROUP: mokomysql
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /source/state.ts
+ * BRIEF: Sidecar state store for learned Joomla markers (per host:port/database).
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { getStatePath } from './config.js';
+import type { JoomlaMarker, MySqlState } from './types.js';
+
+let cache: MySqlState | null = null;
+/** Serializes write-through so concurrent setMarker calls can't clobber the file. */
+let writeChain: Promise<void> = Promise.resolve();
+
+/** Stable key for a learned verdict: identifies the physical database target. */
+export function markerKey(host: string, port: number, database: string): string {
+	return `${host}:${port}/${database}`;
+}
+
+/** Load the sidecar once into memory; a missing/corrupt file is an empty store. */
+export async function loadState(): Promise<MySqlState> {
+	if (cache) return cache;
+	try {
+		const parsed = JSON.parse(await readFile(getStatePath(), 'utf-8')) as Partial<MySqlState>;
+		cache = parsed && typeof parsed.markers === 'object' && parsed.markers !== null
+			? { markers: parsed.markers }
+			: { markers: {} };
+	} catch {
+		cache = { markers: {} };
+	}
+	return cache;
+}
+
+export async function getMarker(key: string): Promise<JoomlaMarker | undefined> {
+	return (await loadState()).markers[key];
+}
+
+/**
+ * Record a learned verdict and persist it. The write is best-effort: an unwritable
+ * sidecar (read-only home, permissions) must not break queries — the in-memory
+ * cache still carries the verdict for this process, we just can't remember it next time.
+ */
+export async function setMarker(key: string, marker: JoomlaMarker): Promise<void> {
+	const state = await loadState();
+	state.markers[key] = marker;
+	writeChain = writeChain.then(async () => {
+		try {
+			await writeFile(getStatePath(), JSON.stringify(state, null, '\t') + '\n', 'utf-8');
+		} catch (e) {
+			process.stderr.write(`mokomysql: could not write state file ${getStatePath()}: ${e}\n`);
+		}
+	});
+	await writeChain;
+}