@mokoconsulting/mokoabs-mcp 0.0.0-stage → 4.0.2

package/sample/config.example.json

@@ -0,0 +1,15 @@
+{
+	"_comment": "No inline secrets. Lead every connection with the file-backed `tokenFile`. An inline `apiKey` is deprecated/legacy and is auto-migrated to ~/.ssh/tokens/<slug>.token.json (and this config rewritten) on first run.",
+	"defaultConnection": "production",
+	"connections": {
+		"production": {
+			"baseUrl": "https://abs.mokoconsulting.tech",
+			"tokenFile": "~/.ssh/tokens/abs.mokoconsulting.tech.token"
+		},
+		"legacy-inline": {
+			"_comment": "DEPRECATED: inline apiKey. Shown only to illustrate the legacy shape; it is auto-migrated to a token file on first run.",
+			"baseUrl": "https://abs.example.com",
+			"apiKey": "legacy-inline-api-key-auto-migrated-on-first-run"
+		}
+	}
+}

package/source/client.ts

@@ -0,0 +1,132 @@
+/* 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: mokoabs-mcp.Client
+ * INGROUP: mokoabs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoabs-mcp
+ * PATH: /source/client.ts
+ * VERSION: 01.00.00
+ * BRIEF: HTTP client for Audiobookshelf API
+ */
+
+import * as https from 'node:https';
+import * as http from 'node:http';
+import type { ApiConnection, ApiResponse } from './types.js';
+
+// ── Customize these ─────────────────────────────────────────────────────
+// API path prefix appended to baseUrl (e.g. "/api/index.php", "/api/v1")
+const API_PREFIX = '/api';
+const TIMEOUT_MS = 30_000;
+// ────────────────────────────────────────────────────────────────────────
+
+export class ApiClient {
+	private readonly base_url: string;
+	private readonly headers: Record<string, string>;
+	private readonly insecure: boolean;
+
+	constructor(conn: ApiConnection) {
+		this.base_url = conn.baseUrl.replace(/\/+$/, '') + API_PREFIX;
+
+		// ── Customize auth headers ──────────────────────────────────
+		// The bearer is resolved at config-load time (MokoCLI #1043) from the
+		// connection's apiKey/tokenFile; fall back to a raw apiKey for safety.
+		// Examples:
+		//   Bearer token:  { 'Authorization': `Bearer ${conn.bearer}` }
+		//   API key header: { 'DOLAPIKEY': conn.bearer }
+		//   Basic auth:    { 'Authorization': `Basic ${btoa(user + ':' + pass)}` }
+		const bearer = conn.bearer ?? conn.apiKey ?? '';
+		this.headers = {
+			'Authorization': `Bearer ${bearer}`,
+			'Content-Type': 'application/json',
+			'Accept': 'application/json',
+		};
+		this.insecure = conn.insecure ?? false;
+	}
+
+	async get(endpoint: string, params?: Record<string, string>): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint, params), 'GET');
+	}
+
+	async post(endpoint: string, body?: unknown): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint), 'POST', body);
+	}
+
+	async put(endpoint: string, body: unknown): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint), 'PUT', body);
+	}
+
+	async patch(endpoint: string, body: unknown): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint), 'PATCH', body);
+	}
+
+	async delete(endpoint: string): Promise<ApiResponse> {
+		return this.request(this.buildUrl(endpoint), 'DELETE');
+	}
+
+	private buildUrl(endpoint: string, params?: Record<string, string>): string {
+		const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+		const url = new URL(`${this.base_url}${path}`);
+		if (params) {
+			for (const [key, value] of Object.entries(params)) {
+				url.searchParams.set(key, value);
+			}
+		}
+		return url.toString();
+	}
+
+	private request(url: string, method: string, body?: unknown): Promise<ApiResponse> {
+		return new Promise((resolve, reject) => {
+			const parsed = new URL(url);
+			const is_https = parsed.protocol === 'https:';
+			const transport = is_https ? https : http;
+
+			const options: https.RequestOptions = {
+				hostname: parsed.hostname,
+				port: parsed.port || (is_https ? 443 : 80),
+				path: parsed.pathname + parsed.search,
+				method,
+				headers: { ...this.headers },
+				timeout: TIMEOUT_MS,
+			};
+
+			if (this.insecure && is_https) {
+				options.rejectUnauthorized = false;
+			}
+
+			const payload = body !== undefined ? JSON.stringify(body) : undefined;
+			if (payload) {
+				(options.headers as Record<string, string>)['Content-Length'] = Buffer.byteLength(payload).toString();
+			}
+
+			const req = transport.request(options, (res) => {
+				const chunks: Buffer[] = [];
+				res.on('data', (chunk: Buffer) => chunks.push(chunk));
+				res.on('end', () => {
+					const raw = Buffer.concat(chunks).toString('utf-8');
+					let data: unknown;
+					try {
+						data = JSON.parse(raw);
+					} catch {
+						data = raw;
+					}
+					resolve({ status: res.statusCode ?? 0, data });
+				});
+			});
+
+			req.on('error', (err) => reject(err));
+			req.on('timeout', () => {
+				req.destroy();
+				reject(new Error('Request timed out'));
+			});
+
+			if (payload) {
+				req.write(payload);
+			}
+			req.end();
+		});
+	}
+}

package/source/config.ts

@@ -0,0 +1,139 @@
+/* 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: mokoabs-mcp.Config
+ * INGROUP: mokoabs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoabs-mcp
+ * PATH: /source/config.ts
+ * VERSION: 01.00.00
+ * BRIEF: Configuration loader for Audiobookshelf MCP connections
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import type { ApiConfig, ApiConnection } from './types.js';
+import { resolveTokenValue, readTokenFile } from './tokenReader.js';
+import { migrateInlineSecret, safeCredentialPath } from './credentialStore.js';
+
+// ── Customize this ──────────────────────────────────────────────────────
+// Change the filename to match your project (e.g. ".dolibarr-api-mcp.json")
+const CONFIG_FILENAME = '.mcp-mokoabs.json';
+// Change the env var name to match your project
+const CONFIG_ENV_VAR = 'MOKOABS_CONFIG';
+// ────────────────────────────────────────────────────────────────────────
+
+export async function loadConfig(): Promise<ApiConfig> {
+	const config_path = process.env[CONFIG_ENV_VAR]
+		? resolve(process.env[CONFIG_ENV_VAR]!)
+		: resolve(homedir(), CONFIG_FILENAME);
+
+	try {
+		const raw = await readFile(config_path, 'utf-8');
+		const parsed = JSON.parse(raw) as Partial<ApiConfig>;
+
+		if (!parsed.connections || Object.keys(parsed.connections).length === 0) {
+			throw new Error('No connections defined in config');
+		}
+
+		// Resolve each connection's credential into a bearer per MokoCLI #1043.
+		// A file-backed `tokenFile` takes precedence over an inline `apiKey`.
+		// Raw bearer strings pass through unchanged (back-compat); GitHub JSON
+		// blobs yield their token/access_token; Google creds are refused. Any
+		// inline `apiKey` literal is warned + auto-migrated to a token file and
+		// the on-disk config is rewritten (no-inline-secrets policy, Pass 2).
+		for (const [name, conn] of Object.entries(parsed.connections)) {
+			await resolveConnectionBearer(conn, name, config_path);
+		}
+
+		return {
+			connections: parsed.connections,
+			defaultConnection: parsed.defaultConnection ?? Object.keys(parsed.connections)[0],
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(
+			`Failed to load config from ${config_path}: ${message}\n` +
+			`Create ${config_path} — see config.example.json for format.`,
+		);
+	}
+}
+
+/**
+ * Resolve a single connection's credential into `conn.bearer` (in place).
+ *
+ * Precedence: a file-backed `tokenFile` wins over an inline `apiKey`. The chosen
+ * credential runs through the MokoCLI #1043 ladder — raw strings pass through,
+ * GitHub JSON yields its token/access_token, Google creds are detected and
+ * refused (unusable bearer). Secret values are never logged.
+ *
+ * No-inline-secrets (Pass 2): a `tokenFile` from the HOME config is a TRUSTED
+ * source and is path-safety-checked (§1b) before being read. An inline `apiKey`
+ * literal is warned + auto-migrated to ~/.ssh/tokens/<slug>.token.json and the
+ * on-disk config rewritten; the current run still uses the resolved bearer even
+ * if migration falls back to warn-only.
+ */
+async function resolveConnectionBearer(conn: ApiConnection, name: string, configPath: string): Promise<void> {
+	let resolved;
+
+	if (conn.tokenFile) {
+		// §1b path safety — the config is a trusted source (HOME / $MOKOABS_CONFIG).
+		const safe = safeCredentialPath(conn.tokenFile, { trusted: true });
+		if (!safe) {
+			throw new Error(`Connection "${name}" tokenFile "${conn.tokenFile}" failed credential-file safety checks (see warning above).`);
+		}
+		resolved = await readTokenFile(safe, `connection "${name}".tokenFile`);
+	} else if (conn.apiKey !== undefined) {
+		// Resolve first (validates shape; raw passes through). Then, if the value
+		// is an inline literal secret, auto-migrate it out of the config.
+		resolved = resolveTokenValue(conn.apiKey, `connection "${name}".apiKey`);
+
+		const migrated = migrateInlineSecret({
+			configPath,
+			connectionName: name,
+			field: 'apiKey',
+			secret: conn.apiKey,
+			baseUrl: conn.baseUrl,
+			primary: true,
+		});
+		if (migrated) {
+			// Reflect the migration in the in-memory config for this run, and use
+			// the FILE as the authoritative secret going forward (§1.6). When an
+			// existing token file was reused, its contents may differ from the
+			// inline value we just resolved — re-resolve from the file so the
+			// current run matches what every future run will use.
+			conn.tokenFile = migrated.tokenFile;
+			delete conn.apiKey;
+			const safe = safeCredentialPath(migrated.tokenFile, { trusted: true });
+			if (safe) {
+				resolved = await readTokenFile(safe, `connection "${name}".tokenFile (migrated)`);
+			}
+		}
+	} else {
+		throw new Error(`Connection "${name}" has neither "apiKey" nor "tokenFile" — nothing to authenticate with.`);
+	}
+
+	if (resolved.needsExchange || !resolved.bearer) {
+		throw new Error(
+			`Connection "${name}" credential is not usable as a bearer token` +
+			(resolved.kind === 'google' ? ' (Google credentials require token exchange, which this server does not perform).' : '.'),
+		);
+	}
+
+	conn.bearer = resolved.bearer;
+}
+
+export function getConnection(config: ApiConfig, name?: string): ApiConnection {
+	const key = name ?? config.defaultConnection;
+	const conn = config.connections[key];
+	if (!conn) {
+		throw new Error(
+			`Connection "${key}" not found. Available: ${Object.keys(config.connections).join(', ')}`,
+		);
+	}
+	return conn;
+}

package/source/credentialStore.ts

@@ -0,0 +1,216 @@
+/* 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: mokoabs-mcp.CredentialStore
+ * INGROUP: mokoabs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoabs-mcp
+ * PATH: /source/credentialStore.ts
+ * VERSION: 01.00.00
+ * BRIEF: No-inline-secrets policy — auto-migration + credential-file path safety.
+ *
+ * Policy (MokoCLI #1043, Pass 2): no secure information may EVER be inline in the
+ * MCP settings file. For mokoabs-mcp the only secret field is a connection's
+ * `apiKey` (the Audiobookshelf bearer). When an inline literal is found in the
+ * on-disk config we warn + auto-migrate it to ~/.ssh/tokens/<slug>.token.json and
+ * rewrite the config to reference it via `tokenFile`. Secret values are NEVER
+ * printed; warnings go to stderr only (stdout is the MCP stdio channel).
+ */
+import { constants as FS } from 'node:fs';
+import {
+	accessSync,
+	chmodSync,
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { expandHome } from './tokenReader.js';
+
+/** stderr ONLY — never stdout; never prints secret values. */
+function warn(msg: string): void {
+	process.stderr.write(`[credential] WARNING: ${msg}\n`);
+}
+
+/** Max size for a credential file we are willing to read (64 KiB). */
+const MAX_CRED_FILE_BYTES = 64 * 1024;
+
+/** Sanitize an arbitrary label into a safe filename fragment ([A-Za-z0-9._-]). */
+function sanitizeSlug(s: string): string {
+	return (s || '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'connection';
+}
+
+/** Derive the host portion of a baseUrl, or '' if unparseable. */
+function hostOf(baseUrl: string | undefined): string {
+	if (!baseUrl) return '';
+	try {
+		return new URL(baseUrl).host;
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * Validate a credential-file reference before it is read (section 1b).
+ * Returns the resolved absolute path when safe, or null (after a stderr warning)
+ * when it must be skipped. `trusted` MUST be false for any reference that came
+ * from an untrusted source (e.g. a cwd .env) — those are never honored as paths.
+ */
+export function safeCredentialPath(ref: string, opts: { trusted: boolean }): string | null {
+	if (!opts.trusted) {
+		warn(`credential-file reference "${ref}" came from an untrusted source (cwd .env) — refusing to open it; provide the secret inline or via the HOME config.`);
+		return null;
+	}
+	const abs = expandHome(ref);
+	const home = resolve(homedir());
+	const rel = relative(home, abs);
+	// Must resolve to a path strictly under $HOME (reject the home dir itself,
+	// any absolute path outside home, and any ".." escape).
+	if (rel === '' || rel.startsWith('..') || rel.split(/[\\/]/).includes('..')) {
+		warn(`credential file "${abs}" is outside $HOME (or escapes it via "..") — refusing to open it.`);
+		return null;
+	}
+	let st;
+	try {
+		st = statSync(abs);
+	} catch (err) {
+		warn(`credential file "${abs}" could not be stat'd (${err instanceof Error ? err.message : String(err)}) — skipping.`);
+		return null;
+	}
+	if (!st.isFile()) {
+		warn(`credential file "${abs}" is not a regular file — skipping.`);
+		return null;
+	}
+	// Owner-read-only: no group/world bits. (On Windows these bits are not
+	// meaningfully enforced, so skip the perm check there to avoid false rejects.)
+	if (process.platform !== 'win32' && (st.mode & 0o077) !== 0) {
+		warn(`credential file "${abs}" is group/world accessible (mode ${(st.mode & 0o777).toString(8)}) — refusing to open it; chmod 600.`);
+		return null;
+	}
+	if (st.size > MAX_CRED_FILE_BYTES) {
+		warn(`credential file "${abs}" is larger than ${MAX_CRED_FILE_BYTES} bytes — refusing to open it (not a credential file).`);
+		return null;
+	}
+	return abs;
+}
+
+export interface MigrationResult {
+	/** Absolute path of the file now holding the secret (may be a pre-existing one). */
+	tokenFile: string;
+}
+
+/**
+ * Auto-migrate an inline secret out of the on-disk config into
+ * ~/.ssh/tokens/<slug>.token.json and rewrite the config to reference it.
+ * Returns the token-file path on success, or null (warn-only) if migration
+ * could not be completed — the caller then keeps using the inline value.
+ *
+ * NEVER throws for an expected failure (read-only FS, perms): warns and returns
+ * null so the server keeps running with the inline value.
+ */
+export function migrateInlineSecret(args: {
+	configPath: string;
+	connectionName: string;
+	field: string;
+	secret: string;
+	baseUrl?: string;
+	/** Whether `field` is the primary bearer field (no suffix) or a secondary one. */
+	primary: boolean;
+}): MigrationResult | null {
+	const { configPath, connectionName, field, secret, baseUrl, primary } = args;
+	try {
+		// Only migrate the real on-disk config (it must exist and be writable).
+		if (!existsSync(configPath)) return null;
+		try {
+			accessSync(configPath, FS.W_OK);
+		} catch {
+			warn(`inline secret ${connectionName}.${field} detected but config "${configPath}" is not writable — keeping inline (warn-only).`);
+			return null;
+		}
+
+		const tokensDir = join(resolve(homedir()), '.ssh', 'tokens');
+		mkdirSync(tokensDir, { recursive: true, mode: 0o700 });
+
+		const base = sanitizeSlug(hostOf(baseUrl) || connectionName);
+		const suffix = primary ? '' : `-${sanitizeSlug(field)}`;
+		const target = join(tokensDir, `${base}${suffix}.token.json`);
+
+		let reusedExisting = false;
+		if (existsSync(target)) {
+			reusedExisting = true;
+		} else {
+			const payload = JSON.stringify(
+				{
+					token: secret,
+					host: hostOf(baseUrl) || undefined,
+					note: 'auto-migrated from inline mokoabs MCP config (no-inline-secrets policy, MokoCLI #1043)',
+					migrated_at: new Date().toISOString(),
+				},
+				null,
+				2,
+			);
+			writeFileSync(target, payload + '\n', { mode: 0o600, flag: 'wx' });
+		}
+
+		// Back up the config ONCE (preserving the old inline secret), then rewrite.
+		const backup = `${configPath}.bak`;
+		if (!existsSync(backup)) {
+			try {
+				copyFileSync(configPath, backup, FS.COPYFILE_EXCL);
+			} catch {
+				// Non-fatal: continue with the rewrite even if the backup races.
+			}
+			try {
+				// Harden the backup perms; it still holds the old secret.
+				chmodSync(backup, 0o600);
+			} catch { /* best-effort */ }
+		}
+
+		rewriteConfigTokenFile(configPath, connectionName, field, target);
+
+		if (reusedExisting) {
+			warn(`inline secret ${connectionName}.${field} migrated: a token file already existed at ${target}; reusing it (did NOT overwrite). Config rewritten to reference it. Backup at ${backup} STILL CONTAINS the old inline secret — delete it after verifying.`);
+		} else {
+			warn(`inline secret ${connectionName}.${field} migrated to ${target} (mode 0600) and config rewritten to reference it via tokenFile. Backup at ${backup} STILL CONTAINS the old inline secret — delete ${backup} after verifying the migration.`);
+		}
+		return { tokenFile: target };
+	} catch (err) {
+		warn(`auto-migration of ${connectionName}.${field} failed (${err instanceof Error ? err.message : String(err)}) — keeping inline value (warn-only).`);
+		return null;
+	}
+}
+
+/**
+ * Atomically rewrite the config: set connection[field→tokenFile] = target and
+ * delete the inline `field`. Preserves all other fields; writes temp + rename.
+ */
+function rewriteConfigTokenFile(configPath: string, connectionName: string, field: string, target: string): void {
+	const raw = readFileSync(configPath, 'utf-8');
+	const parsed = JSON.parse(raw) as {
+		connections?: Record<string, Record<string, unknown>>;
+		[k: string]: unknown;
+	};
+	const conn = parsed.connections?.[connectionName];
+	if (!conn) throw new Error(`connection "${connectionName}" vanished from config`);
+
+	// Map the inline secret field to its file-ref field. For mokoabs the only
+	// secret is apiKey → tokenFile; a generic *_password would map to *File.
+	const fileField = field === 'apiKey' ? 'tokenFile' : `${field}File`;
+	conn[fileField] = `~/${relative(resolve(homedir()), target).split(/[\\/]/).join('/')}`;
+	delete conn[field];
+
+	const tmp = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+	writeFileSync(tmp, JSON.stringify(parsed, null, '\t') + '\n', { mode: 0o600 });
+	renameSync(tmp, configPath);
+	try {
+		chmodSync(configPath, 0o600);
+	} catch { /* best-effort on platforms without POSIX perms */ }
+}