@mokoconsulting/mokogit-mcp 1.13.4 → 1.14.0

package/CODE_OF_CONDUCT.md

@@ -14,7 +14,7 @@
 	DEFGROUP: 
 	INGROUP: Project.Documentation
 	REPO: MokoConsulting/mokogit-mcp
-	VERSION: 00.00.01
+	VERSION: 01.14.00
 	PATH: ./CODE_OF_CONDUCT.md
 	BRIEF: Contributor Covenant Code of Conduct version 1.3.0
 -->

package/CONTRIBUTING.md

@@ -14,7 +14,7 @@
 	DEFGROUP: 
 	INGROUP: Project.Documentation
 	REPO: https://git.mokoconsulting.tech/MokoConsulting/mokogit-mcp
-	VERSION: 00.00.01
+	VERSION: 01.14.00
 	PATH: ./CONTRIBUTING.md
 	BRIEF: Contribution guidelines for the project
 -->

package/Makefile

@@ -10,7 +10,7 @@
 # Identity (auto-filled by workflow sync — the Makefile is the version source of truth)
 # ==============================================================================
 PROJECT_NAME    := mcp-mokogit
-PROJECT_VERSION := 1.13.4
+PROJECT_VERSION := 01.14.00
 PLATFORM        := npm
 
 # ==============================================================================

package/config.example.json

@@ -1,13 +1,15 @@
 {
+	"//": "NO INLINE SECRETS. Point each connection at a token FILE via tokenFile. An inline \"token\" is legacy and is auto-migrated to ~/.ssh/tokens/<host>.token.json on first run (the config is rewritten and a .bak is kept). The token file may hold a raw PAT or a JSON blob {token|access_token, expires_*, scope(s), permissions}; Google service-account/OAuth creds are detected and refused (no token exchange).",
 	"defaultConnection": "moko",
 	"connections": {
 		"moko": {
 			"baseUrl": "https://git.mokoconsulting.tech",
-			"token": "your-git-access-token"
+			"tokenFile": "~/.ssh/tokens/git.mokoconsulting.tech.jmiller.token"
 		},
 		"github-mirror": {
 			"baseUrl": "https://git.example.com",
-			"token": "your-other-token"
+			"tokenFile": "~/.ssh/tokens/git.example.com.token",
+			"//token": "legacy: an inline \"token\": \"...\" here still works but is auto-migrated to a tokenFile on first run (no-inline-secrets policy)"
 		}
 	}
 }

package/dist/index.js

@@ -24,6 +24,7 @@ import { GitClient } from './client.js';
 import { setGeneratedConfig, setGeneratedServer, setRegisteredNames, } from './generated-runtime.js';
 import { registerGeneratedToolsV2 } from './tools.generated.js';
 import { resolveGuardConfig, runGuardedMerge } from './rapid-merge-guard.js';
+import { probeBackends, warnBackendStatus, runMokoCli, cliRunEnabled, assertSafeArgs } from './mokocli.js';
 import { investigatePremergeCi, evaluatePremergeGate, renderPremergeReport, } from './premerge-ci.js';
 let config;
 function clientFor(connection) {
@@ -252,6 +253,44 @@ function registerTool(name, description, paramsSchema, cb) {
 }
 // ── User / Auth ─────────────────────────────────────────────────────────
 registerTool('git_me', 'Get the authenticated user info', { ...ConnectionParam }, async ({ connection }) => formatResponse(await clientFor(connection).get('/user')));
+// ── Operation backends: mokogit-cli (MokoCLI) — precedence api > mokogit-cli > git ──
+//
+// The REST API is the PRIMARY path: every other tool here calls it directly, and
+// that is what you should use for anything the API covers. The mokogit-cli binary
+// is a FALLBACK backend for CLI-only operations (or when the API is unavailable);
+// plain git is the last resort. These two tools expose that layer.
+registerTool('cli_status', 'Report the MokoGIT MCP operation backends and their precedence (api > mokogit-cli > git): which are available, the resolved mokogit-cli/git binary paths and versions, and the active backend. The REST API is always primary; mokogit-cli and git are fallbacks. Use this to check whether CLI-assisted operations are available on this host.', {}, async () => {
+    const status = await probeBackends();
+    return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
+});
+registerTool('cli_run', 'Run a mokogit-cli (MokoCLI) subcommand as a FALLBACK backend and return its exit code, stdout and stderr. DISABLED by default — an operator must opt in with $MOKOGIT_ENABLE_CLI_RUN=1 (arbitrary CLI execution). Precedence is api > mokogit-cli > git — prefer the REST API tools for anything they cover; use this only for CLI-only operations or when the API is unavailable. Arguments are passed as argv (no shell); option-like args (leading "-") are rejected unless allowlisted or $MOKOGIT_CLI_ALLOW_FLAGS=1; any cwd must be inside $MOKOGIT_CLI_WORKDIR. Refuses with a clear message when disabled or when mokogit-cli is not installed (check cli_status).', {
+    args: z.array(z.string()).describe('mokogit-cli arguments as an argv array, e.g. ["version"] or ["repo","list"]. Passed directly to the binary (no shell).'),
+    cwd: z.string().optional().describe('Working directory — must resolve inside $MOKOGIT_CLI_WORKDIR (optional).'),
+    timeout_seconds: z.number().int().positive().max(600).optional().describe('Max run time in seconds (default 60).'),
+    input: z.string().optional().describe('Optional data to write to the CLI’s stdin.'),
+}, async ({ args, cwd, timeout_seconds, input }) => {
+    if (!cliRunEnabled()) {
+        return { content: [{ type: 'text', text: 'cli_run is disabled. Arbitrary mokogit-cli execution is an operator opt-in — set $MOKOGIT_ENABLE_CLI_RUN=1 to enable it. The REST API tools are the primary path (precedence api > mokogit-cli > git); use cli_status to see backend availability.' }] };
+    }
+    try {
+        assertSafeArgs(args);
+        const r = await runMokoCli(args, {
+            cwd,
+            timeoutMs: timeout_seconds ? timeout_seconds * 1000 : undefined,
+            input,
+        });
+        const text = [
+            `$ ${r.command}`,
+            `exit: ${r.code}${r.ok ? '' : ' (non-zero)'}`,
+            r.stdout ? `\n--- stdout ---\n${r.stdout.trimEnd()}` : '',
+            r.stderr ? `\n--- stderr ---\n${r.stderr.trimEnd()}` : '',
+        ].filter(Boolean).join('\n');
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }] };
+    }
+});
 registerTool('git_user_orgs', 'List organizations the authenticated user belongs to', { ...PaginationParams, ...ConnectionParam }, async ({ page, limit, connection }) => formatResponse(await clientFor(connection).get('/user/orgs', pageQuery({ page, limit }))));
 registerTool('git_user_repos', 'List repositories owned by the authenticated user', { ...PaginationParams, ...ConnectionParam }, async ({ page, limit, connection }) => formatResponse(await clientFor(connection).get('/user/repos', pageQuery({ page, limit }))));
 // ── Repository CRUD ─────────────────────────────────────────────────────
@@ -1437,7 +1476,7 @@ registerTool('git_repo_mirror_setup_github_backup', 'One-step GitHub backup mirr
     const client = clientFor(connection);
     const results = [];
     // 1. Try to create the GitHub repo via GitHub API
-    const ghRes = await fetch(`https://api.github.com/orgs/${ghOrg}/repos`, {
+    const ghRes = await fetch(`https://api.github.com/orgs/${enc(ghOrg)}/repos`, {
         method: 'POST',
         headers: {
             'Authorization': `Bearer ${ghToken}`,
@@ -1503,7 +1542,7 @@ registerTool('git_repo_mirror_setup_github_backup_full', 'Full GitHub backup: mi
     const syncInterval = interval ?? '8h0m0s';
     const results = [];
     // 1. Create GitHub repo (if needed)
-    const ghRes = await fetch(`https://api.github.com/orgs/${ghOrg}/repos`, {
+    const ghRes = await fetch(`https://api.github.com/orgs/${enc(ghOrg)}/repos`, {
         method: 'POST',
         headers: {
             'Authorization': `Bearer ${ghToken}`,
@@ -1531,7 +1570,7 @@ registerTool('git_repo_mirror_setup_github_backup_full', 'Full GitHub backup: mi
         return { content: [{ type: 'text', text: `GitHub repo creation failed (${ghRes.status}): ${JSON.stringify(ghData)}` }] };
     }
     // 2. Enable wiki on GitHub repo (in case it was disabled)
-    await fetch(`https://api.github.com/repos/${ghOrg}/${repo}`, {
+    await fetch(`https://api.github.com/repos/${enc(ghOrg)}/${enc(repo)}`, {
         method: 'PATCH',
         headers: {
             'Authorization': `Bearer ${ghToken}`,
@@ -1606,7 +1645,7 @@ registerTool('git_admin_cron_list', 'List cron tasks and their last run time (ad
 registerTool('git_admin_cron_run', 'Trigger a cron task (admin only)', {
     task: z.string().describe('Cron task name (e.g. "repo_health_check", "resync_all_hooks", "repo_archive_cleanup")'),
     ...ConnectionParam,
-}, async ({ task, connection }) => formatResponse(await clientFor(connection).post(`/admin/cron/${task}`, {})));
+}, async ({ task, connection }) => formatResponse(await clientFor(connection).post(`/admin/cron/${enc(task)}`, {})));
 // ── Generic API Call ────────────────────────────────────────────────────
 registerTool('git_api_request', 'Make a raw API request to any Git v1 endpoint', {
     method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
@@ -4400,6 +4439,15 @@ async function main() {
     setGeneratedServer(server);
     setRegisteredNames(registeredNames);
     registerGeneratedToolsV2();
+    // Detect the operation backends (API > mokogit-cli > git) and emit a one-time,
+    // non-fatal status line. The REST API is the primary path; mokogit-cli/git are
+    // fallbacks. Detection must never block startup, so swallow any probe error.
+    try {
+        warnBackendStatus(await probeBackends());
+    }
+    catch {
+        /* detection is best-effort; the server runs API-only regardless */
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mokoconsulting/mokogit-mcp",
-	"version": "1.13.4",
+	"version": "1.14.0",
 	"description": "MCP server for MokoGIT (Git) REST API v1 operations",
 	"type": "module",
 	"main": "dist/index.js",

package/source/config.ts

@@ -13,10 +13,11 @@
  * BRIEF: Configuration loader for MokoGIT API MCP connections
  */
 
-import { readFile, access } from 'node:fs/promises';
+import { readFile, writeFile, rename, access } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { homedir } from 'node:os';
 import type { GitConfig, GitConnection } from './types.js';
+import { resolveTokenValue, readTokenFile, migrateInlineSecret, warn } from './tokenReader.js';
 
 // Canonical config filename. Older installs may still use a pre-rename name, which
 // is read as a fallback so they keep working after the Gitea → MokoGIT rename.
@@ -60,6 +61,42 @@ async function resolveConfigPath(): Promise<string> {
 	return primary;
 }
 
+/** Extract a hostname from a baseUrl, or '' when it cannot be parsed. */
+function hostOf(baseUrl: string | undefined): string {
+	if (!baseUrl) return '';
+	try {
+		return new URL(baseUrl).host;
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * Atomically rewrite the config file after a migration, preserving a leading BOM
+ * if the original had one and backing up to <config>.bak once. mode 0600.
+ * Throws on I/O failure so the caller can fall back to warn-only.
+ */
+async function rewriteConfigAtomic(configPath: string, hadBom: boolean, data: Record<string, unknown>): Promise<void> {
+	// One-time backup of the original on-disk file.
+	const bak = `${configPath}.bak`;
+	try {
+		await access(bak);
+		// .bak already exists → leave it (first-migration snapshot is the one to keep).
+	} catch {
+		try {
+			const original = await readFile(configPath, 'utf-8');
+			await writeFile(bak, original, { mode: 0o600 });
+		} catch {
+			/* best-effort; absence of a backup must not block the fix */
+		}
+	}
+
+	const body = (hadBom ? '' : '') + JSON.stringify(data, null, '\t') + '\n';
+	const tmp = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+	await writeFile(tmp, body, { mode: 0o600 });
+	await rename(tmp, configPath);
+}
+
 export async function loadConfig(): Promise<GitConfig> {
 	const config_path = await resolveConfigPath();
 
@@ -67,8 +104,12 @@ export async function loadConfig(): Promise<GitConfig> {
 		const raw = await readFile(config_path, 'utf-8');
 		// #192: a config file saved with a UTF-8 BOM makes JSON.parse throw
 		// "Unexpected token" and the MCP fails to start. Strip a leading BOM first.
-		const clean = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
-		const parsed = JSON.parse(clean) as Partial<GitConfig>;
+		const hadBom = raw.charCodeAt(0) === 0xfeff;
+		const clean = hadBom ? raw.slice(1) : raw;
+		// Keep the full parsed document (not just the typed view) so a migration
+		// rewrite preserves every field we do not touch.
+		const parsedFull = JSON.parse(clean) as Record<string, unknown>;
+		const parsed = parsedFull as Partial<GitConfig> & Record<string, unknown>;
 
 		if (!parsed.connections || Object.keys(parsed.connections).length === 0) {
 			throw new Error('No connections defined in config');
@@ -77,9 +118,91 @@ export async function loadConfig(): Promise<GitConfig> {
 		// A token injected via env is the single source of truth — apply it over
 		// whatever the config file holds so a rotated token cannot leave it stale.
 		const envToken = envTokenOverride();
-		if (envToken) {
-			for (const conn of Object.values(parsed.connections)) {
-				conn.token = envToken;
+
+		// Resolve each connection's credential through the MokoCLI #1043 JSON-aware
+		// token ladder, enforcing the no-inline-secrets policy (pass 2).
+		//
+		// Precedence per connection:
+		//   1. env override (MOKOGIT_TOKEN/MOKOGITEA_TOKEN/GITEA_TOKEN) — single source
+		//      of truth. If the value is an inline literal we WARN only (there is no
+		//      config line to rewrite) and still use it.
+		//   2. conn.tokenFile — file-backed; read with §1b path-safety guards.
+		//   3. inline conn.token — WARN + AUTO-MIGRATE to ~/.ssh/tokens/<slug>.token.json,
+		//      rewrite this config to a tokenFile ref, delete the inline token, and use
+		//      the migrated file this run. On any migration error, fall back to warn-only
+		//      and keep running with the inline value (never crash, never lose the cred).
+		//
+		// A bare PAT round-trips unchanged (back-compat). A Google creds JSON is detected,
+		// warned on stderr, and left unusable (empty bearer). A needs-exchange / empty /
+		// skipped bearer is allowed to surface at use time (401), not crash at load, so one
+		// bad connection cannot take the whole server down. Secrets are never logged.
+		//
+		// mokogit-mcp sources its config only from $HOME (~/.mcp_mokogit.json) or an
+		// explicit $MOKOGIT_MCP_CONFIG / $GITEA_API_MCP_CONFIG override — both TRUSTED
+		// sources (§1b). There is NO cwd `.env` loader here, so every tokenFile reference
+		// is trusted; we pass trusted=true explicitly.
+		// Deep clone of the on-disk document that we mutate for the rewrite ONLY. The
+		// runtime objects (parsed.connections[*]) get their `.token` set to the resolved
+		// bearer for the HTTP header; the on-disk copy must instead carry a tokenFile ref
+		// and NO inline token. Keeping them separate avoids re-leaking the bearer we just
+		// assigned to the live object back into the file.
+		const rewriteDoc = JSON.parse(JSON.stringify(parsedFull)) as Record<string, unknown>;
+		const rewriteConns = rewriteDoc.connections as Record<string, Record<string, unknown>>;
+
+		let configMutated = false;
+		for (const [name, conn] of Object.entries(parsed.connections)) {
+			if (envToken) {
+				if (typeof conn.token === 'string' && conn.token.trim() && !conn.tokenFile) {
+					warn(`connection "${name}" has an inline token in the config AND an env override is set; the env token is used. The inline token is still a policy violation — move it to a tokenFile or remove it.`);
+				}
+				conn.token = resolveTokenValue(envToken, `env (${name})`).bearer;
+				continue;
+			}
+
+			if (conn.tokenFile) {
+				conn.token = (await readTokenFile(conn.tokenFile, `${name}.tokenFile`, true)).bearer;
+				continue;
+			}
+
+			// Inline literal → warn + migrate.
+			const inline = typeof conn.token === 'string' ? conn.token : '';
+			if (!inline.trim()) {
+				// Empty/missing inline token: surface the empty-credential error as before.
+				conn.token = resolveTokenValue(inline, `${name}.token`).bearer;
+				continue;
+			}
+
+			const host = hostOf(conn.baseUrl);
+			const slug = host || name;
+			try {
+				const { tokenFile, created } = await migrateInlineSecret(inline, slug, host, 'mokogit');
+				if (created) {
+					warn(`connection "${name}": inline "token" migrated to a file (no-inline-secrets policy); config rewritten to tokenFile and the inline token removed.`);
+				} else {
+					warn(`connection "${name}": inline "token" found but ${tokenFile} already exists; reusing it (not overwritten) and rewriting config to a tokenFile ref.`);
+				}
+				// Rewrite THIS connection in the on-disk clone: set tokenFile, drop inline token.
+				const connRewrite = rewriteConns[name];
+				connRewrite.tokenFile = tokenFile;
+				delete connRewrite.token;
+				conn.tokenFile = tokenFile;
+				configMutated = true;
+				// Use the migrated file this run (path-safety guards apply).
+				conn.token = (await readTokenFile(tokenFile, `${name}.tokenFile`, true)).bearer;
+			} catch (err) {
+				// Migration failed (read-only FS, perms, …): warn-only, keep running inline.
+				warn(`connection "${name}": could not migrate inline token to a file (${err instanceof Error ? err.message : String(err)}); continuing with the inline value for this run (fix manually — no-inline-secrets policy).`);
+				conn.token = resolveTokenValue(inline, `${name}.token`).bearer;
+			}
+		}
+
+		if (configMutated) {
+			try {
+				await rewriteConfigAtomic(config_path, hadBom, rewriteDoc);
+			} catch (err) {
+				// The migrated token files are written; only the config rewrite failed.
+				// Warn and keep running — the resolved bearers are already in memory.
+				warn(`migrated inline token(s) to files but could not rewrite ${config_path} (${err instanceof Error ? err.message : String(err)}); the inline token(s) remain in the config — fix the file manually.`);
 			}
 		}
 

package/source/index.ts

@@ -31,6 +31,7 @@ import {
 } from './generated-runtime.js';
 import { registerGeneratedToolsV2 } from './tools.generated.js';
 import { resolveGuardConfig, runGuardedMerge } from './rapid-merge-guard.js';
+import { probeBackends, warnBackendStatus, runMokoCli, cliRunEnabled, assertSafeArgs } from './mokocli.js';
 import {
 	investigatePremergeCi,
 	evaluatePremergeGate,
@@ -297,6 +298,56 @@ registerTool(
 	async ({ connection }) => formatResponse(await clientFor(connection).get('/user')),
 );
 
+// ── Operation backends: mokogit-cli (MokoCLI) — precedence api > mokogit-cli > git ──
+//
+// The REST API is the PRIMARY path: every other tool here calls it directly, and
+// that is what you should use for anything the API covers. The mokogit-cli binary
+// is a FALLBACK backend for CLI-only operations (or when the API is unavailable);
+// plain git is the last resort. These two tools expose that layer.
+
+registerTool(
+	'cli_status',
+	'Report the MokoGIT MCP operation backends and their precedence (api > mokogit-cli > git): which are available, the resolved mokogit-cli/git binary paths and versions, and the active backend. The REST API is always primary; mokogit-cli and git are fallbacks. Use this to check whether CLI-assisted operations are available on this host.',
+	{},
+	async () => {
+		const status = await probeBackends();
+		return { content: [{ type: 'text' as const, text: JSON.stringify(status, null, 2) }] };
+	},
+);
+
+registerTool(
+	'cli_run',
+	'Run a mokogit-cli (MokoCLI) subcommand as a FALLBACK backend and return its exit code, stdout and stderr. DISABLED by default — an operator must opt in with $MOKOGIT_ENABLE_CLI_RUN=1 (arbitrary CLI execution). Precedence is api > mokogit-cli > git — prefer the REST API tools for anything they cover; use this only for CLI-only operations or when the API is unavailable. Arguments are passed as argv (no shell); option-like args (leading "-") are rejected unless allowlisted or $MOKOGIT_CLI_ALLOW_FLAGS=1; any cwd must be inside $MOKOGIT_CLI_WORKDIR. Refuses with a clear message when disabled or when mokogit-cli is not installed (check cli_status).',
+	{
+		args: z.array(z.string()).describe('mokogit-cli arguments as an argv array, e.g. ["version"] or ["repo","list"]. Passed directly to the binary (no shell).'),
+		cwd: z.string().optional().describe('Working directory — must resolve inside $MOKOGIT_CLI_WORKDIR (optional).'),
+		timeout_seconds: z.number().int().positive().max(600).optional().describe('Max run time in seconds (default 60).'),
+		input: z.string().optional().describe('Optional data to write to the CLI’s stdin.'),
+	},
+	async ({ args, cwd, timeout_seconds, input }) => {
+		if (!cliRunEnabled()) {
+			return { content: [{ type: 'text' as const, text: 'cli_run is disabled. Arbitrary mokogit-cli execution is an operator opt-in — set $MOKOGIT_ENABLE_CLI_RUN=1 to enable it. The REST API tools are the primary path (precedence api > mokogit-cli > git); use cli_status to see backend availability.' }] };
+		}
+		try {
+			assertSafeArgs(args);
+			const r = await runMokoCli(args, {
+				cwd,
+				timeoutMs: timeout_seconds ? timeout_seconds * 1000 : undefined,
+				input,
+			});
+			const text = [
+				`$ ${r.command}`,
+				`exit: ${r.code}${r.ok ? '' : ' (non-zero)'}`,
+				r.stdout ? `\n--- stdout ---\n${r.stdout.trimEnd()}` : '',
+				r.stderr ? `\n--- stderr ---\n${r.stderr.trimEnd()}` : '',
+			].filter(Boolean).join('\n');
+			return { content: [{ type: 'text' as const, text }] };
+		} catch (err) {
+			return { content: [{ type: 'text' as const, text: err instanceof Error ? err.message : String(err) }] };
+		}
+	},
+);
+
 registerTool(
 	'git_user_orgs',
 	'List organizations the authenticated user belongs to',
@@ -2048,7 +2099,7 @@ registerTool(
 		const results: string[] = [];
 
 		// 1. Try to create the GitHub repo via GitHub API
-		const ghRes = await fetch(`https://api.github.com/orgs/${ghOrg}/repos`, {
+		const ghRes = await fetch(`https://api.github.com/orgs/${enc(ghOrg)}/repos`, {
 			method: 'POST',
 			headers: {
 				'Authorization': `Bearer ${ghToken}`,
@@ -2120,7 +2171,7 @@ registerTool(
 		const results: string[] = [];
 
 		// 1. Create GitHub repo (if needed)
-		const ghRes = await fetch(`https://api.github.com/orgs/${ghOrg}/repos`, {
+		const ghRes = await fetch(`https://api.github.com/orgs/${enc(ghOrg)}/repos`, {
 			method: 'POST',
 			headers: {
 				'Authorization': `Bearer ${ghToken}`,
@@ -2147,7 +2198,7 @@ registerTool(
 		}
 
 		// 2. Enable wiki on GitHub repo (in case it was disabled)
-		await fetch(`https://api.github.com/repos/${ghOrg}/${repo}`, {
+		await fetch(`https://api.github.com/repos/${enc(ghOrg)}/${enc(repo)}`, {
 			method: 'PATCH',
 			headers: {
 				'Authorization': `Bearer ${ghToken}`,
@@ -2275,7 +2326,7 @@ registerTool(
 		task: z.string().describe('Cron task name (e.g. "repo_health_check", "resync_all_hooks", "repo_archive_cleanup")'),
 		...ConnectionParam,
 	},
-	async ({ task, connection }) => formatResponse(await clientFor(connection).post(`/admin/cron/${task}`, {})),
+	async ({ task, connection }) => formatResponse(await clientFor(connection).post(`/admin/cron/${enc(task)}`, {})),
 );
 
 // ── Generic API Call ────────────────────────────────────────────────────
@@ -7178,6 +7229,14 @@ async function main(): Promise<void> {
 	setGeneratedServer(server);
 	setRegisteredNames(registeredNames);
 	registerGeneratedToolsV2();
+	// Detect the operation backends (API > mokogit-cli > git) and emit a one-time,
+	// non-fatal status line. The REST API is the primary path; mokogit-cli/git are
+	// fallbacks. Detection must never block startup, so swallow any probe error.
+	try {
+		warnBackendStatus(await probeBackends());
+	} catch {
+		/* detection is best-effort; the server runs API-only regardless */
+	}
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 }

package/source/mokocli.ts

@@ -0,0 +1,328 @@
+/* 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: mokogit-mcp.MokoCli
+ * INGROUP: mokogit-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokogit-mcp
+ * PATH: /source/mokocli.ts
+ * VERSION: 01.00.00
+ * BRIEF: Operation-backend detection + invocation for the MokoGIT MCP.
+ *        Resolves the mokogit-cli (MokoCLI) binary and plain git at runtime and
+ *        exposes them as FALLBACK backends behind the REST API. Fleet precedence
+ *        is API > mokogit-cli > git: the REST API is always the primary path, the
+ *        CLI is the first fallback, git the last. Detection is non-fatal — when a
+ *        binary is absent the MCP warns once on stderr and keeps running API-only.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { statSync, realpathSync } from 'node:fs';
+import { delimiter, join, isAbsolute, resolve, sep } from 'node:path';
+
+const execFileP = promisify(execFile);
+const IS_WIN = process.platform === 'win32';
+
+/**
+ * Resolve a binary name/path to an ABSOLUTE path by searching $PATH explicitly
+ * (like `which`/`where`), honoring PATHEXT on Windows. Returns null when not
+ * found. Running the resolved absolute path — never a bare name — prevents
+ * cwd-relative / planted-binary resolution (Windows CreateProcess search order).
+ */
+function resolveExecutable(nameOrPath: string): string | null {
+	const isFile = (p: string): boolean => {
+		try { return statSync(p).isFile(); } catch { return false; }
+	};
+	// Explicit path (absolute or contains a separator): accept only if it is a file.
+	// On Windows, refuse a .bat/.cmd target (BatBadBut — argv is not safely escaped
+	// when execFile spawns cmd.exe for a batch file), even when set via $MOKOGIT_CLI.
+	if (isAbsolute(nameOrPath) || nameOrPath.includes('/') || (IS_WIN && nameOrPath.includes('\\'))) {
+		if (IS_WIN && /\.(bat|cmd)$/i.test(nameOrPath)) return null;
+		const abs = resolve(nameOrPath);
+		return isFile(abs) ? abs : null;
+	}
+	// Bare name: search PATH directories in order. NEVER include '.' / cwd.
+	// On Windows accept ONLY .EXE/.COM — never .BAT/.CMD. Running a batch file via
+	// execFile spawns cmd.exe and argv is not safely escaped (BatBadBut / CVE-2024-27980),
+	// so a batch target would reintroduce command injection through args. Honor
+	// PATHEXT order but intersect it with the exe/com allowlist.
+	const WIN_SAFE_EXTS = ['.COM', '.EXE'];
+	const exts = IS_WIN
+		? (() => {
+			const fromEnv = (process.env.PATHEXT ?? '').split(';').map((e) => e.trim().toUpperCase()).filter((e) => WIN_SAFE_EXTS.includes(e));
+			return fromEnv.length ? fromEnv : WIN_SAFE_EXTS;
+		})()
+		: [''];
+	const dirs = (process.env.PATH ?? '').split(delimiter).filter((d) => d && d.trim() && d !== '.');
+	for (const dir of dirs) {
+		for (const ext of exts) {
+			const cand = join(dir, nameOrPath + (IS_WIN ? ext : ''));
+			if (isFile(cand)) return resolve(cand);
+		}
+	}
+	return null;
+}
+
+/** Operation backends, in fleet precedence order (highest first). */
+export const BACKEND_PRECEDENCE = ['api', 'mokogit-cli', 'git'] as const;
+export type Backend = (typeof BACKEND_PRECEDENCE)[number];
+
+/** Candidate binary names searched on PATH for the MokoCLI, in order. */
+const MOKOCLI_CANDIDATES = ['mokogit-cli', 'mokogit', 'mokocli'];
+/** Env vars that may hold an explicit MokoCLI path (checked before PATH). */
+const MOKOCLI_ENV_VARS = ['MOKOGIT_CLI', 'MOKOCLI', 'MOKOGIT_CLI_PATH'];
+
+const VERSION_TIMEOUT_MS = 5000;
+
+export interface BinaryProbe {
+	available: boolean;
+	/** Resolved command (an absolute path from an env var, or a PATH-resolved name). */
+	path: string | null;
+	/** First line of `--version` output, when it could be read. */
+	version: string | null;
+	/** How it was resolved: an env var name, 'path', or null when not found. */
+	source: string | null;
+}
+
+export interface BackendStatus {
+	/** Static precedence order (API > mokogit-cli > git). */
+	precedence: Backend[];
+	/** The REST API is always the primary path; reachability is per-request. */
+	api: { available: true; note: string };
+	mokogitCli: BinaryProbe & { envVarsChecked: string[]; candidates: string[] };
+	git: BinaryProbe;
+	/** Available backends in precedence order (api is always present). */
+	availableChain: Backend[];
+	/** Highest-precedence backend usable for a generic op — always 'api'. */
+	active: Backend;
+}
+
+/** Run `<bin> <versionArgs>` and return its trimmed first output line, or null. */
+async function readVersion(bin: string, versionArgs: string[]): Promise<string | null> {
+	try {
+		const { stdout, stderr } = await execFileP(bin, versionArgs, {
+			timeout: VERSION_TIMEOUT_MS,
+			windowsHide: true,
+		});
+		const out = (stdout || stderr || '').trim();
+		return out ? out.split(/\r?\n/, 1)[0].trim() : '';
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Probe for a binary: try each env var (as an explicit command/path) first, then
+ * each PATH candidate, accepting the first whose `--version` runs successfully.
+ */
+async function probeBinary(
+	envVars: string[],
+	candidates: string[],
+	versionArgs: string[] = ['--version'],
+): Promise<BinaryProbe> {
+	for (const ev of envVars) {
+		const val = process.env[ev];
+		if (val && val.trim()) {
+			const abs = resolveExecutable(val.trim());
+			if (abs) {
+				const ver = await readVersion(abs, versionArgs);
+				if (ver !== null) return { available: true, path: abs, version: ver || null, source: ev };
+			}
+		}
+	}
+	for (const name of candidates) {
+		const abs = resolveExecutable(name);
+		if (abs) {
+			const ver = await readVersion(abs, versionArgs);
+			if (ver !== null) return { available: true, path: abs, version: ver || null, source: 'path' };
+		}
+	}
+	return { available: false, path: null, version: null, source: null };
+}
+
+/**
+ * Build a MINIMAL environment for the child process: only the variables the CLI
+ * needs to locate itself, find its home/temp, and authenticate — never the full
+ * parent environment. Prevents leaking unrelated secrets into the subprocess.
+ */
+function minimalChildEnv(): NodeJS.ProcessEnv {
+	const allow = [
+		'PATH', 'Path', 'PATHEXT', 'SystemRoot', 'windir', 'ComSpec',
+		'TEMP', 'TMP', 'TMPDIR', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH',
+		'LANG', 'LC_ALL', 'LC_CTYPE',
+		// MokoGIT auth / CLI config the CLI may need to operate
+		'MOKOGIT_TOKEN', 'MOKOGITEA_TOKEN', 'GITEA_TOKEN',
+		'MOKOGIT_CLI', 'MOKOCLI', 'MOKOGIT_CLI_PATH',
+		'MOKOGIT_MCP_CONFIG', 'GITEA_API_MCP_CONFIG',
+		'MOKOGIT_HOST', 'MOKOGIT_URL',
+	];
+	const env: NodeJS.ProcessEnv = {};
+	for (const k of allow) if (process.env[k] !== undefined) env[k] = process.env[k];
+	return env;
+}
+
+/**
+ * Validate a caller-supplied cwd. Running the CLI in an arbitrary directory is a
+ * risk (relative config/hook pickup), so a cwd is honored ONLY when it resolves
+ * inside the operator-configured workspace root $MOKOGIT_CLI_WORKDIR. Returns the
+ * resolved cwd to use, or throws. When no cwd is requested, the configured root
+ * (if any) is used; otherwise the child inherits the MCP's own cwd.
+ */
+function resolveCwd(requested?: string): string | undefined {
+	const rootRaw = process.env.MOKOGIT_CLI_WORKDIR;
+	const root = rootRaw && rootRaw.trim() ? realpathSync(resolve(rootRaw.trim())) : null;
+	if (!requested) return root ?? undefined;
+	if (!root) {
+		throw new Error('A cwd was requested but no workspace root is configured. Set $MOKOGIT_CLI_WORKDIR to an allowed directory to use cwd.');
+	}
+	let abs: string;
+	try { abs = realpathSync(resolve(root, requested)); } catch { throw new Error(`cwd does not exist or is not accessible: ${requested}`); }
+	if (abs !== root && !abs.startsWith(root + sep)) {
+		throw new Error(`cwd must be inside the configured workspace root ($MOKOGIT_CLI_WORKDIR): ${root}`);
+	}
+	return abs;
+}
+
+let cached: Promise<BackendStatus> | null = null;
+
+/** Detect the available operation backends. Cached after the first call. */
+export function probeBackends(force = false): Promise<BackendStatus> {
+	if (cached && !force) return cached;
+	cached = (async (): Promise<BackendStatus> => {
+		const [cli, git] = await Promise.all([
+			probeBinary(MOKOCLI_ENV_VARS, MOKOCLI_CANDIDATES),
+			probeBinary([], ['git']),
+		]);
+		const availableChain: Backend[] = ['api'];
+		if (cli.available) availableChain.push('mokogit-cli');
+		if (git.available) availableChain.push('git');
+		return {
+			precedence: [...BACKEND_PRECEDENCE],
+			api: { available: true, note: 'primary path — all MCP tools call the MokoGIT REST API directly' },
+			mokogitCli: { ...cli, envVarsChecked: MOKOCLI_ENV_VARS, candidates: MOKOCLI_CANDIDATES },
+			git,
+			availableChain,
+			active: 'api',
+		};
+	})();
+	return cached;
+}
+
+let warned = false;
+
+/**
+ * Emit a one-time, non-fatal status line to stderr describing backend
+ * availability. Absence of the CLI is informational, not an error — the REST API
+ * is the primary path and the server runs fine without the CLI.
+ */
+export function warnBackendStatus(status: BackendStatus): void {
+	if (warned) return;
+	warned = true;
+	if (status.mokogitCli.available) {
+		process.stderr.write(
+			`mokogit-cli detected (${status.mokogitCli.path}${status.mokogitCli.version ? ` — ${status.mokogitCli.version}` : ''}); ` +
+			`available as a fallback backend. Precedence: api > mokogit-cli > git.\n`,
+		);
+	} else {
+		process.stderr.write(
+			`mokogit-cli not found (checked ${MOKOCLI_ENV_VARS.join('/')} and PATH: ${MOKOCLI_CANDIDATES.join(', ')}). ` +
+			`CLI-assisted fallback is disabled — operating API-only (precedence api > mokogit-cli > git). ` +
+			`Install mokogit-cli or set $MOKOGIT_CLI to enable it.\n`,
+		);
+	}
+}
+
+export interface CliRunResult {
+	ok: boolean;
+	code: number | null;
+	stdout: string;
+	stderr: string;
+	command: string;
+}
+
+const RUN_TIMEOUT_MS = 60000;
+const MAX_BUFFER = 8 * 1024 * 1024;
+
+const TRUTHY = /^(1|true|on|yes)$/i;
+
+/**
+ * Whether the cli_run passthrough is enabled. Arbitrary CLI execution is an
+ * explicit operator opt-in and is DISABLED by default — set
+ * $MOKOGIT_ENABLE_CLI_RUN=1 to allow it.
+ */
+export function cliRunEnabled(): boolean {
+	return TRUTHY.test((process.env.MOKOGIT_ENABLE_CLI_RUN ?? '').trim());
+}
+
+/** Global flags permitted even though they start with '-'. */
+const ALLOWED_FLAGS = new Set(['-h', '--help', '-v', '--version', '--json']);
+
+/**
+ * Reject option-like args (leading '-') not in the allowlist, so a default-on
+ * cli_run cannot be handed arbitrary flags. Operators who need full flags set
+ * $MOKOGIT_CLI_ALLOW_FLAGS=1. Throws with a clear message on a rejected arg.
+ */
+export function assertSafeArgs(args: string[]): void {
+	if (TRUTHY.test((process.env.MOKOGIT_CLI_ALLOW_FLAGS ?? '').trim())) return;
+	for (const a of args) {
+		if (a.startsWith('-') && !ALLOWED_FLAGS.has(a)) {
+			throw new Error(
+				`Refused: option-like argument "${a}" is not allowed by default. ` +
+				`Allowed flags: ${[...ALLOWED_FLAGS].join(', ')}. Set $MOKOGIT_CLI_ALLOW_FLAGS=1 to permit arbitrary flags.`,
+			);
+		}
+	}
+}
+
+/**
+ * Invoke the resolved mokogit-cli with argv (NOT a shell string — no shell
+ * interpolation). Throws if the CLI is unavailable; resolves with the exit code,
+ * stdout and stderr otherwise (a non-zero exit is returned, not thrown).
+ */
+export async function runMokoCli(
+	args: string[],
+	opts: { cwd?: string; timeoutMs?: number; input?: string } = {},
+): Promise<CliRunResult> {
+	const status = await probeBackends();
+	if (!status.mokogitCli.available || !status.mokogitCli.path) {
+		throw new Error(
+			'mokogit-cli is not available on this host (checked ' +
+			`${MOKOCLI_ENV_VARS.join('/')} and PATH: ${MOKOCLI_CANDIDATES.join(', ')}). ` +
+			'Use the REST API tools (primary path), or install mokogit-cli / set $MOKOGIT_CLI.',
+		);
+	}
+	// status.mokogitCli.path is an ABSOLUTE path resolved at probe time via an
+	// explicit PATH search — we never exec a bare name (no cwd-relative/planted
+	// binary). cwd is allowlisted to $MOKOGIT_CLI_WORKDIR; the child gets a minimal
+	// environment and no shell (execFile passes argv directly).
+	const bin = status.mokogitCli.path;
+	const cwd = resolveCwd(opts.cwd);
+	const command = `${bin} ${args.join(' ')}`;
+	try {
+		const child = execFileP(bin, args, {
+			cwd,
+			timeout: opts.timeoutMs ?? RUN_TIMEOUT_MS,
+			maxBuffer: MAX_BUFFER,
+			windowsHide: true,
+			shell: false,
+			env: minimalChildEnv(),
+		});
+		if (opts.input !== undefined && child.child.stdin) {
+			child.child.stdin.end(opts.input);
+		}
+		const { stdout, stderr } = await child;
+		return { ok: true, code: 0, stdout: stdout ?? '', stderr: stderr ?? '', command };
+	} catch (err) {
+		const e = err as { code?: number; stdout?: string; stderr?: string; message?: string };
+		return {
+			ok: false,
+			code: typeof e.code === 'number' ? e.code : null,
+			stdout: e.stdout ?? '',
+			stderr: e.stderr ?? e.message ?? String(err),
+			command,
+		};
+	}
+}

package/source/tokenReader.ts

@@ -0,0 +1,231 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * MokoCLI #1043 — JSON-aware credential/token reader (vendored per-repo).
+ * GitHub standard primary; Google secondary = DETECT + WARN (no exchange).
+ * Secret values are NEVER written to stdout and NEVER echoed in errors/warnings.
+ *
+ * Detection ladder (resolveTokenValue):
+ *   1. trim; empty -> throw (no silent anonymous request).
+ *   2. JSON.parse; parse-fail OR non-object(array/null/scalar) -> the trimmed
+ *      string IS the bearer (bare PAT, `gh auth token` output).  [raw]
+ *   3. object .type in {service_account, authorized_user, external_account,
+ *      impersonated_service_account}  OR  (.refresh_token && .token_uri)
+ *      -> GOOGLE: emit a stderr WARNING and return an UNUSABLE result
+ *         (bearer '', needsExchange true). Never bearer a private key.
+ *   4. else .token || .access_token -> bearer (+ expiry/scope/permissions). [github-json]
+ *   5. else -> throw (unrecognized object; never leak the blob as a token).
+ */
+import { readFile, writeFile, rename, mkdir, stat, access, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve, sep } from 'node:path';
+
+export type TokenKind = 'raw' | 'github-json' | 'google';
+
+export interface ResolvedToken {
+	/** Bearer value to send. '' when unusable (Google needs-exchange). */
+	bearer: string;
+	kind: TokenKind;
+	/** true for Google creds — not usable as a bearer by this server. */
+	needsExchange?: boolean;
+	expiresAt?: string;
+	expiresIn?: number;
+	scopes?: string[];
+	permissions?: Record<string, unknown>;
+}
+
+const GOOGLE_TYPES = new Set([
+	'service_account',
+	'authorized_user',
+	'external_account',
+	'impersonated_service_account',
+]);
+
+/** Expand a leading "~" to $HOME, then resolve to an absolute path. */
+export function expandHome(p: string): string {
+	if (p === '~') return homedir();
+	if (p.startsWith('~/') || p.startsWith('~\\')) return resolve(homedir(), p.slice(2));
+	return resolve(p);
+}
+
+/** stderr ONLY — must never touch stdout (the MCP stdio channel). Never prints secret values. */
+export function warn(msg: string): void {
+	process.stderr.write(`[token] WARNING: ${msg}\n`);
+}
+
+/** Largest credential file we will open (§1b path-safety cap). */
+const MAX_TOKEN_FILE_BYTES = 64 * 1024;
+
+/** Reduce an arbitrary label to the safe slug charset [A-Za-z0-9._-]. */
+export function sanitizeSlug(s: string): string {
+	return (s || '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'connection';
+}
+
+/** True when `abs` is $HOME itself or lives beneath it (no `..` escape). */
+function isWithinHome(abs: string): boolean {
+	const home = resolve(homedir());
+	return abs === home || abs.startsWith(home + sep);
+}
+
+/**
+ * Resolve RAW credential content into a bearer per MokoCLI #1043.
+ * `source` only labels errors/warnings; secret values are never echoed.
+ */
+export function resolveTokenValue(raw: string, source = 'credential'): ResolvedToken {
+	const trimmed = (raw ?? '').trim();
+	if (!trimmed) {
+		throw new Error(`Credential "${source}" is empty — refusing an anonymous request (set the token or remove the connection).`);
+	}
+
+	let obj: unknown;
+	try {
+		obj = JSON.parse(trimmed);
+	} catch {
+		return { bearer: trimmed, kind: 'raw' }; // bare PAT / `gh auth token`
+	}
+	if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+		return { bearer: trimmed, kind: 'raw' };
+	}
+
+	const o = obj as Record<string, unknown>;
+	const type = typeof o.type === 'string' ? o.type : '';
+	const isGoogle = GOOGLE_TYPES.has(type) || (typeof o.refresh_token === 'string' && typeof o.token_uri === 'string');
+	if (isGoogle) {
+		warn(`credential "${source}" is a Google ${type || 'OAuth token-cache'} JSON; this server does not perform Google token exchange, so it will NOT be used (a private key is never sent as a bearer token).`);
+		return { bearer: '', kind: 'google', needsExchange: true };
+	}
+
+	const bearer = typeof o.token === 'string' ? o.token : typeof o.access_token === 'string' ? o.access_token : '';
+	if (bearer) {
+		const scopes = Array.isArray(o.scopes)
+			? o.scopes.map(String)
+			: typeof o.scope === 'string'
+				? o.scope.split(/\s+/).filter(Boolean)
+				: undefined;
+		const expiresAt = typeof o.expires_at === 'string' ? o.expires_at : typeof o.expiry === 'string' ? o.expiry : undefined;
+		const expiresIn = typeof o.expires_in === 'number' ? o.expires_in : undefined;
+		const permissions = o.permissions && typeof o.permissions === 'object' ? (o.permissions as Record<string, unknown>) : undefined;
+		return { bearer, kind: 'github-json', expiresAt, expiresIn, scopes, permissions };
+	}
+
+	throw new Error(`Credential "${source}" is an unrecognized JSON object (no "token"/"access_token") — refusing to use it as a bearer token.`);
+}
+
+/**
+ * Read a token file (~ expands) and resolve it per #1043, with §1b PATH SAFETY.
+ *
+ * A credential-file reference can otherwise be abused to read an arbitrary local
+ * file (e.g. a path pointing at /etc/shadow or ~/.ssh/id_rsa) and exfiltrate it as
+ * a bearer to an attacker-controlled target. Only honor a reference from a TRUSTED
+ * config source (the process environment or the user's HOME config / explicit
+ * $..._CONFIG). mokogit-mcp has NO cwd `.env` loader, so every tokenFile reference
+ * here already comes from a trusted source; `trusted` defaults to true and is passed
+ * explicitly from config.ts for clarity / future-proofing.
+ *
+ * Path constraints enforced before the file is opened: regular file, located under
+ * $HOME (no absolute-outside-home, no `..` escape), owner-read/write only
+ * (mode & 0o077 === 0), size ≤ 64 KiB. On any failure: stderr WARN naming the path
+ * + reason and SKIP (return an unusable result) — never read/send its contents,
+ * never crash. Files we auto-write (migrateInlineSecret) are 0600 under
+ * ~/.ssh/tokens, so they always pass.
+ */
+export async function readTokenFile(path: string, source?: string, trusted = true): Promise<ResolvedToken> {
+	const abs = expandHome(path);
+	const label = source ?? abs;
+
+	if (!trusted) {
+		warn(`refusing credential-file reference "${abs}" from an untrusted source (${label}); a file path is only honored from env or the HOME config — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+
+	if (!isWithinHome(abs)) {
+		warn(`credential file "${abs}" (${label}) is outside $HOME — refusing to read it (path-safety) — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+
+	let st: Awaited<ReturnType<typeof stat>>;
+	try {
+		st = await stat(abs);
+	} catch (err) {
+		warn(`credential file "${abs}" (${label}) could not be stat'd: ${err instanceof Error ? err.message : String(err)} — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+	if (!st.isFile()) {
+		warn(`credential file "${abs}" (${label}) is not a regular file — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+	// Owner-only perms: no group/world read/write/execute bits. Windows / MSYS do
+	// not model POSIX perms (stat.mode returns synthetic 0666/0444 regardless of the
+	// real ACL), so the check is POSIX-only; on win32 it is skipped and the file is
+	// trusted on the strength of the within-$HOME + regular-file + size guards.
+	if (process.platform !== 'win32' && (st.mode & 0o077) !== 0) {
+		warn(`credential file "${abs}" (${label}) is group/world-accessible (mode ${(st.mode & 0o777).toString(8)}); run \`chmod 600 "${abs}"\` — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+	if (st.size > MAX_TOKEN_FILE_BYTES) {
+		warn(`credential file "${abs}" (${label}) is ${st.size} bytes (> ${MAX_TOKEN_FILE_BYTES} cap) — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+
+	let raw: string;
+	try {
+		raw = await readFile(abs, 'utf-8');
+	} catch (err) {
+		warn(`failed to read credential file "${abs}" (${label}): ${err instanceof Error ? err.message : String(err)} — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+	return resolveTokenValue(raw, label);
+}
+
+export interface MigrationResult {
+	/** Absolute path of the token file now holding the secret. */
+	tokenFile: string;
+	/** true when this call created the file; false when an existing file was reused. */
+	created: boolean;
+}
+
+/**
+ * §1 AUTO-MIGRATE an inline secret to ~/.ssh/tokens/<slug>.token.json (self-heal).
+ *
+ * Writes { token, host, note, migrated_at } at mode 0600 (never overwriting an
+ * existing file), and returns the path so the caller can rewrite the config to a
+ * tokenFile reference and drop the inline value. The secret is NEVER logged. The
+ * caller is responsible for the config rewrite + .bak; this function only owns the
+ * token-file side. Throws on I/O failure so the caller can fall back to warn-only.
+ */
+export async function migrateInlineSecret(secret: string, slug: string, host: string, serverName: string): Promise<MigrationResult> {
+	const tokensDir = resolve(homedir(), '.ssh', 'tokens');
+	await mkdir(tokensDir, { recursive: true, mode: 0o700 });
+
+	const target = resolve(tokensDir, `${sanitizeSlug(slug)}.token.json`);
+
+	// Do not clobber an existing token file — reuse it instead.
+	try {
+		await access(target);
+		return { tokenFile: target, created: false };
+	} catch {
+		// does not exist → write it
+	}
+
+	const payload = JSON.stringify(
+		{
+			token: secret,
+			host: host || undefined,
+			note: `auto-migrated from inline ${serverName} MCP config (no-inline-secrets policy, MokoCLI #1043)`,
+			migrated_at: new Date().toISOString(),
+		},
+		null,
+		'\t',
+	);
+
+	// Atomic-ish: write a sibling temp 0600, then rename into place.
+	const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+	await writeFile(tmp, payload + '\n', { mode: 0o600 });
+	try {
+		await chmod(tmp, 0o600);
+	} catch {
+		/* best-effort on platforms without POSIX perms */
+	}
+	await rename(tmp, target);
+	return { tokenFile: target, created: true };
+}

package/source/types.ts

@@ -16,6 +16,12 @@
 export interface GitConnection {
 	baseUrl: string;
 	token: string;
+	/**
+	 * Optional path to a file holding the token/credential (MokoCLI #1043).
+	 * Read via readTokenFile and resolved through the JSON-aware token ladder;
+	 * "~" expands to $HOME. Takes effect only when no env override is present.
+	 */
+	tokenFile?: string;
 	/** Skip TLS certificate verification (self-signed certs) */
 	insecure?: boolean;
 }