copilot-relay 0.3.1 → 0.3.3

package/README.md

@@ -140,9 +140,28 @@ copilot-relay 0.2.5
   models     gpt-5.6-sol[1m], claude-opus-5
   upstream   not checked (use --deep)
   log        ~/.copilot-relay/logs/copilot-relay.2026-07-25.log
-  config     ~/.copilot-relay/config.yaml (logLevel=info, thinkEffort=max)
+  config     ~/.copilot-relay/config.yaml
+    host                    127.0.0.1
+    port                    4142
+    copilotBaseUrl          https://api.githubcopilot.com
+    claudeSetup             true
+    logLevel                info
+    logRetentionDays        3
+    thinkEffort             max
+    upstreamTimeoutSeconds  180
+    webSearchBackend        (unset — uses gptModel)
+    gptModel                gpt-5.6-sol
+    opusModel               claude-opus-5
+    host, port and claudeSetup take effect on restart; the rest hot-reload.
 ```
 
+The `config` block is every key `readAppConfig()` resolved, in
+`config.default.yaml` order. These are the values on disk: eight of them reload
+while the relay runs, while `host`, `port` and `claudeSetup` are read once at
+startup — the block says so rather than leaving you to discover it after an
+edit. `--json` emits the same values under `config`, with `webSearchBackend` as
+`null` when unset so the key set stays the same shape either way.
+
 The first line is the CLI you invoked; the `version` row is the build the
 running daemon reports about itself. They differ after an upgrade that has not
 been restarted yet — the new CLI is installed, the old process is still
@@ -192,7 +211,8 @@ tail -f ~/.copilot-relay/logs/copilot-relay.$(date +%F).log
 grep -n "Failed to create\\|Startup preflight failed" ~/.copilot-relay/logs/copilot-relay.*.log
 ```
 
-See [`docs/troubleshooting.md`](docs/troubleshooting.md) for common debugging workflows.
+See [Logs and troubleshooting](wiki/EN-Logging-Troubleshooting.md)
+([中文](wiki/ZH-Logging-Troubleshooting.md)) for common debugging workflows.
 
 ## Running it as a service
 
@@ -206,11 +226,15 @@ which is generated from `wiki/` on every merge. Edit the folder, not the tab.
 
 ## Development
 
-Developer notes live in [`docs/development.md`](docs/development.md).
-Architecture notes live in [`docs/architecture.md`](docs/architecture.md).
-Logging notes live in [`docs/logging.md`](docs/logging.md).
-Troubleshooting notes live in [`docs/troubleshooting.md`](docs/troubleshooting.md).
-User-facing guides live in [`wiki/`](wiki/).
+All documentation lives in [`wiki/`](wiki/), in English and 中文:
+
+| Page | Covers |
+| --- | --- |
+| [Architecture](wiki/EN-Architecture.md) ([中文](wiki/ZH-Architecture.md)) | Modules, request and startup flow, public API, runtime files |
+| [Internals](wiki/EN-Internals.md) ([中文](wiki/ZH-Internals.md)) | Translation, streaming, prompt caching, lifecycle, logging invariants |
+| [Development](wiki/EN-Development.md) ([中文](wiki/ZH-Development.md)) | Setup, tests, CI matrix, workflow, releasing |
+| [Configuration](wiki/EN-Configuration.md) ([中文](wiki/ZH-Configuration.md)) | Every config key, hot reload vs restart |
+| [Logs and troubleshooting](wiki/EN-Logging-Troubleshooting.md) ([中文](wiki/ZH-Logging-Troubleshooting.md)) | Log format, grep recipes, failure modes |
 
 ```sh
 npm install

package/dist/main.js

@@ -119,6 +119,124 @@ async function ensureFile(filePath, options = {}) {
 	}
 }
 
+//#endregion
+//#region src/lib/redact.ts
+/**
+* Origins known to carry a secret somewhere after the origin.
+*
+* Process-lifetime and append-only. Never pruned, because config hot-reload can
+* change copilotBaseUrl while a request against the previous one is still in
+* flight; dropping the old policy would un-redact that request's error on its
+* way to the log.
+*/
+const sensitiveOrigins = /* @__PURE__ */ new Set();
+/** Marker written in place of everything after the origin. */
+const redactedMarker = "[redacted]";
+/**
+* ANSI escape sequences: CSI (`ESC [ … final`), OSC (`ESC ] … BEL/ST`), and the
+* two-byte Fe forms. Matched whole rather than stripping the ESC byte alone,
+* which would leave the printable remainder (`[2K`) in the output.
+*
+* Written with \x escapes rather than literal bytes: an invisible ESC in the
+* source survives no round trip through an editor, a diff view, or a paste.
+*/
+const ansiEscapePattern = /\x1B(?:\[[0-?]*[ -/]*[@-~]|\][\s\S]*?(?:\x07|\x1B\\)|[@-Z\\-_])/g;
+/** C0 controls and DEL, including CR/LF: one config value is one row. */
+const controlBytePattern = /[\x00-\x1F\x7F]/g;
+/**
+* Absolute http(s) URLs inside arbitrary text.
+*
+* Stops at whitespace, quotes, backticks and angle brackets so a URL embedded
+* in inspect() output — `url: 'https://host/x'` — matches without swallowing
+* the surrounding punctuation.
+*
+* Backslashes are consumed rather than terminating the match. WHATWG folds `\`
+* into `/` for http(s), so `https://host\tenant\TOKEN` parses with the tail in
+* the path, carries no userinfo, and is therefore accepted and stored verbatim
+* by normalizeCopilotBaseUrl — and inspect() doubles each backslash on the way
+* to both sinks. Stopping at the first one matched only the origin, which then
+* looked origin-only and left the entire tail in the log.
+*/
+const absoluteUrlPattern = /https?:\/\/[^\s'"`<>]+/gi;
+const parseHttpUrl = (value) => {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return;
+	}
+	return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed : void 0;
+};
+/** True when the URL carries nothing after the origin worth hiding. */
+const isOriginOnly = (parsed) => (parsed.pathname === "" || parsed.pathname === "/") && !parsed.search && !parsed.hash;
+/**
+* Renders a URL for display, keeping the origin and hiding the rest.
+*
+* The origin is the operationally useful half — it answers "which gateway am I
+* talking to" — while path, query and fragment are where a credential ends up.
+* An explicit marker rather than silent truncation, so a reader can tell the
+* difference between a base URL that has no path and one whose path was
+* withheld.
+*
+* Never throws: it also runs on values that failed validation.
+*/
+const formatUrlForDisplay = (raw) => {
+	const parsed = parseHttpUrl(raw);
+	if (!parsed) return "(invalid url)";
+	return isOriginOnly(parsed) ? raw : `${parsed.origin} (path/query/fragment hidden)`;
+};
+/**
+* Strips ANSI escapes and control bytes from a string bound for the terminal.
+*
+* `status` prints config values directly to stdout. A config string carrying
+* raw control bytes could clear the line and paint status rows the relay never
+* produced. The config file is user-owned, so this is hardening rather than a
+* vulnerability — but it costs nothing to make the output non-forgeable. #47.
+*/
+const sanitizeTerminalString = (text) => text.replace(ansiEscapePattern, "").replace(controlBytePattern, "");
+/**
+* Marks a URL's origin as secret-bearing, if it has anything after the origin.
+*
+* An origin-only URL registers nothing: there is no tail to hide, and marking
+* the origin would redact every unrelated URL on that host for no benefit.
+*
+* Additive and idempotent. Never throws on an unparseable value.
+*/
+const registerSensitiveOrigin = (raw) => {
+	const parsed = parseHttpUrl(raw);
+	if (!parsed || isOriginOnly(parsed)) return;
+	sensitiveOrigins.add(parsed.origin);
+};
+/**
+* Rewrites URLs on registered origins to `origin[redacted]`.
+*
+* Anchored on the parsed origin rather than on the configured string, which is
+* what makes the variants match: fetch reports back a canonicalized URL (host
+* case-folded, default port dropped) with the fragment already stripped, and
+* clients append their own endpoint to the base. All of those share an origin.
+*
+* Deliberately not a substring substitution of the secret path. Replacing that
+* text wherever it appeared would also rewrite unrelated prose and detached
+* paths; only an absolute URL on a registered origin is rewritten here.
+*/
+const scrubSensitiveUrls = (text) => {
+	if (sensitiveOrigins.size === 0) return text;
+	return text.replace(absoluteUrlPattern, (match) => {
+		const parsed = parseHttpUrl(match);
+		if (!parsed || !sensitiveOrigins.has(parsed.origin)) return match;
+		const authorityStart = match.indexOf("://") + 3;
+		let authorityEnd = match.length;
+		for (let index = authorityStart; index < match.length; index += 1) {
+			const character = match[index];
+			if (character === "/" || character === "\\" || character === "?" || character === "#") {
+				authorityEnd = index;
+				break;
+			}
+		}
+		return authorityEnd === match.length ? match : `${parsed.origin}${redactedMarker}`;
+	});
+};
+
 //#endregion
 //#region src/lib/log.ts
 const logCleanupCheckIntervalMs = 3600 * 1e3;
@@ -147,8 +265,9 @@ const setLogLevel = (level) => {
 * `breakLength: Infinity` matters as much as the depth cap. The previous
 * `inspect(value, { depth: null })` pretty-printed each payload across
 * thousands of physical lines, which was both the dominant source of log volume
-* and the reason the `grep` recipes in docs/logging.md returned a fragment of an
-* object instead of the matching entry. One entry is now one line.
+* and the reason the `grep` recipes in wiki/EN-Logging-Troubleshooting.md
+* returned a fragment of an object instead of the matching entry. One entry is
+* now one line.
 */
 const formatLogValue = (value) => typeof value === "string" ? value : inspect(value, {
 	breakLength: Infinity,
@@ -157,13 +276,21 @@ const formatLogValue = (value) => typeof value === "string" ? value : inspect(va
 	maxArrayLength: 100,
 	maxStringLength: 4e3
 });
+/**
+* Appends one already-rendered entry.
+*
+* Takes strings rather than raw values: rendering happens once in wrapFileLog,
+* so the console and the file are guaranteed to carry the same redacted text.
+* Inspecting again here would reintroduce the gap this closes - the file would
+* be scrubbed while the console showed the original object. See #47.
+*/
 const writeLogFile = async (level, values) => {
 	await fs.mkdir(paths.logsDir, { recursive: true });
 	await cleanupLogsIfDue();
 	const line = [
 		(/* @__PURE__ */ new Date()).toISOString(),
 		level,
-		values.map(formatLogValue).join(" ")
+		values.join(" ")
 	].join(" ");
 	await fs.appendFile(getLogPath(), `${line}\n`);
 };
@@ -173,9 +300,27 @@ const cleanupLogsIfDue = async () => {
 	nextLogCleanupCheckAt = now + logCleanupCheckIntervalMs;
 	await cleanupLogs(logRetentionDays);
 };
+/**
+* The single boundary where every logged value becomes redacted text.
+*
+* Each argument is rendered exactly once and scrubbed once, and the identical
+* array of strings goes to both the file and the console. Scrubbing only on the
+* way to disk would leave the original object on the console - the screen a
+* user screenshots into an issue - so the two sinks must not diverge. See #47.
+*
+* Rendering is skipped only when neither sink would emit, so the cost matches
+* the old behavior at info level. The console gate is read from consola rather
+* than assumed equal to currentLogLevel: if the two ever diverge, rendering
+* must follow whichever sink is still emitting, or that sink gets raw values.
+*/
 const wrapFileLog = (level, fn) => ((...args) => {
-	if ((fileLevelByMethod[level] ?? consolaLevelByName.info) <= currentLogLevel) writeLogFile(level, args).catch(() => void 0);
-	return fn(...args);
+	const methodLevel = fileLevelByMethod[level] ?? consolaLevelByName.info;
+	const writesToFile = methodLevel <= currentLogLevel;
+	const writesToConsole = methodLevel <= consola.level;
+	if (!writesToFile && !writesToConsole) return fn(...args);
+	const rendered = args.map((value) => scrubSensitiveUrls(formatLogValue(value)));
+	if (writesToFile) writeLogFile(level, rendered).catch(() => void 0);
+	return fn(...rendered);
 });
 consola.error = wrapFileLog("error", consola.error.bind(consola));
 consola.info = wrapFileLog("info", consola.info.bind(consola));
@@ -480,6 +625,87 @@ const normalizePositiveInteger = (value) => {
 	return Number.isInteger(number) && number > 0 ? number : void 0;
 };
 const normalizeString = (value) => typeof value === "string" && value.trim() ? value.trim() : void 0;
+/**
+* A conventional http(s) URL: scheme followed by a literal "//" authority.
+*
+* WHATWG is far more permissive than this. `https:host/path`, `https:/host/path`
+* and `https:\\host\path` all parse, all normalize to a real origin with the
+* tail in the path, and all work upstream - so a protocol check alone lets them
+* through. None of them can be found again in arbitrary log text: practical URL
+* detection anchors on a literal "://", and loosening that to chase a bare
+* "https:" would start matching ordinary prose. Requiring the authority prefix
+* is the one boundary where this has a definite answer. See #47.
+*/
+const conventionalHttpUrlPattern = /^https?:\/\//i;
+/**
+* Raw characters that cannot be delimited safely in rendered log text.
+*
+* A raw apostrophe is the clearest case. WHATWG accepts it and leaves it raw
+* in the path, so the configured value keeps it - and inspect() renders that
+* value inside quotes, where the apostrophe reads as the closing delimiter.
+* Any URL scan ends there, and the rest of the path prints in full. Quotes,
+* backticks and angle brackets are the same story; whitespace ends a URL for
+* every reader and scanner alike; and tab and newline are worse still,
+* because URL parsing strips them, so the stored value would not even match
+* what is sent upstream.
+*
+* Rejecting the raw byte costs nothing: every one of these has a
+* percent-encoded spelling that is unambiguous in log text and is accepted
+* here unchanged. See #47.
+*/
+const unsafeRawDelimiterPattern = /['"`<>\s\u0000-\u001F\u007F]/;
+/**
+* Both fixed strings. The rejected value is never interpolated: these messages
+* reach the terminal and, via the startup failure path, the log file, which is
+* exactly the disclosure being prevented.
+*/
+const invalidCopilotBaseUrlMessage = "Invalid copilotBaseUrl: expected an absolute http(s) URL, e.g. https://api.githubcopilot.com";
+const copilotBaseUrlCredentialsMessage = "Invalid copilotBaseUrl: URL credentials (user:password@host) are not supported; remove them and use a plain https URL";
+const copilotBaseUrlDelimiterMessage = "Invalid copilotBaseUrl: quotes, backticks, angle brackets, whitespace and control characters must be percent-encoded";
+/**
+* Validates copilotBaseUrl as a conventional HTTP(S) URL without credentials.
+*
+* Four rules, all learned from #47:
+*
+* The value is concatenated as `${base}${path}` for every upstream call, so it
+* must be something Undici will accept. A relative or non-HTTP value fails at
+* request time as an unrelated-looking fetch error; failing here names the key.
+*
+* It must be written with an explicit `http://` or `https://` authority. See
+* conventionalHttpUrlPattern: the shorthand forms WHATWG also accepts are
+* unfindable in log text, so a configured secret in one of them cannot be
+* redacted by anything downstream. Rejecting is the only safe answer, and this
+* is the only place with enough context to give it.
+*
+* Raw quote-like characters, angle brackets, whitespace and control bytes are
+* rejected for the same reason - see unsafeRawDelimiterPattern. They are what
+* marks the end of a URL in rendered text, so a value containing one cannot be
+* matched whole afterwards. Their percent-encoded forms are accepted.
+*
+* URL userinfo (`https://user:pass@host`) is rejected rather than passed
+* through. Undici refuses it at request time anyway, so accepting it buys only
+* a confusing failure plus a credential written to the log on every start.
+*
+* The accepted value is returned as the trimmed original, never URL-normalized.
+* Round-tripping through URL would add a trailing slash, lowercase the host and
+* re-encode the path, silently changing both the request URL and what gets
+* written back to config.yaml.
+*/
+const normalizeCopilotBaseUrl = (value) => {
+	const trimmed = normalizeString(value);
+	if (trimmed === void 0) return;
+	if (!conventionalHttpUrlPattern.test(trimmed)) throw new Error(invalidCopilotBaseUrlMessage);
+	if (unsafeRawDelimiterPattern.test(trimmed)) throw new Error(copilotBaseUrlDelimiterMessage);
+	let parsed;
+	try {
+		parsed = new URL(trimmed);
+	} catch {
+		throw new Error(invalidCopilotBaseUrlMessage);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(invalidCopilotBaseUrlMessage);
+	if (parsed.username || parsed.password) throw new Error(copilotBaseUrlCredentialsMessage);
+	return trimmed;
+};
 const normalizeThinkEffort = (value) => {
 	if (typeof value !== "string") return;
 	const normalized = value.toLowerCase() === "minimal" ? "low" : value.toLowerCase();
@@ -640,7 +866,7 @@ async function readAppConfig() {
 	const upstreamTimeoutSeconds = normalizeUpstreamTimeoutSeconds(raw.upstreamTimeoutSeconds);
 	const config = {
 		claudeSetup: claudeSetup ?? defaultConfig.claudeSetup,
-		copilotBaseUrl: normalizeString(raw.copilotBaseUrl) ?? defaultConfig.copilotBaseUrl,
+		copilotBaseUrl: normalizeCopilotBaseUrl(raw.copilotBaseUrl) ?? defaultConfig.copilotBaseUrl,
 		gptModel: normalizeString(raw.gptModel) ?? defaultConfig.gptModel,
 		host: host ?? defaultConfig.host,
 		logLevel: logLevel ?? defaultConfig.logLevel,
@@ -3193,6 +3419,7 @@ async function startRelay(appConfig) {
 	const claudeConfigPath$1 = claudeConfigPath;
 	const config = readProxyConfig(appConfig);
 	const applyRuntimeConfig = (nextConfig) => {
+		registerSensitiveOrigin(nextConfig.copilotBaseUrl);
 		setLogLevel(nextConfig.logLevel);
 		cleanupLogs(nextConfig.logRetentionDays);
 		runtimeState.debug = nextConfig.logLevel === "debug";
@@ -3225,7 +3452,7 @@ async function startRelay(appConfig) {
 	if (authSession.githubLogin) log.info(`GitHub user: ${authSession.githubLogin}`);
 	else log.error("GitHub user: unavailable");
 	log.info(`copilot-relay listening on http://${config.host}:${config.port}`);
-	log.info(`copilot base url: ${config.copilotBaseUrl}`);
+	log.info(`copilot base url: ${formatUrlForDisplay(config.copilotBaseUrl)}`);
 	const baseUrl = `http://${config.host}:${config.port}`;
 	if (appConfig.claudeSetup) try {
 		const claudeResult = await applyClaudeConfig({
@@ -3320,6 +3547,11 @@ const exitCodes = {
 };
 const localProbeTimeoutMs = 5e3;
 const deepProbeTimeoutMs = 6e4;
+const toStatusConfig = (config) => ({
+	...config,
+	copilotBaseUrl: formatUrlForDisplay(config.copilotBaseUrl),
+	webSearchBackend: config.webSearchBackend ?? null
+});
 /**
 * True when the daemon is serving a different build than the invoked CLI.
 *
@@ -3354,13 +3586,58 @@ const formatUptime = (startedAt) => {
 	return `${Math.floor(seconds / 86400)}d ${Math.floor(seconds % 86400 / 3600)}h`;
 };
 /**
+* Every config key with its position in the block, in config.default.yaml order
+* rather than alphabetical so it reads like the file it was resolved from.
+*
+* A Record keyed by StatusConfig rather than an array of keys: an array only
+* checks that each entry *is* a key, so a twelfth config key would type-check
+* while silently never appearing in `status` — the exact failure this command
+* exists to prevent. Keyed this way, adding one fails the build here.
+*/
+const configRowOrder = {
+	host: 0,
+	port: 1,
+	copilotBaseUrl: 2,
+	claudeSetup: 3,
+	logLevel: 4,
+	logRetentionDays: 5,
+	thinkEffort: 6,
+	upstreamTimeoutSeconds: 7,
+	webSearchBackend: 8,
+	gptModel: 9,
+	opusModel: 10
+};
+const configRowKeys = Object.keys(configRowOrder).sort((a, b) => configRowOrder[a] - configRowOrder[b]);
+/**
+* The resolved config, one key per line.
+*
+* These are the values on disk. That is not the same question as "what is the
+* running daemon honouring", and the footnote says so rather than leaving it
+* implied: applyRuntimeConfig() in start.ts hot-reloads eight of these keys,
+* never reads claudeSetup, and deliberately does not rebind the listening
+* socket when host or port changes. Printing all eleven without that line
+* would imply a live daemon had read values it has not.
+*
+* Only shown when running, because with nothing up every value applies at the
+* next start and the note would be noise.
+*/
+const renderConfig = (config, running) => {
+	const lines = configRowKeys.map((key) => {
+		const value = config[key];
+		const rendered = key === "webSearchBackend" && value === null ? "(unset — uses gptModel)" : String(value);
+		return `    ${key.padEnd(24)}${sanitizeTerminalString(rendered)}`;
+	});
+	if (running) lines.push("    host, port and claudeSetup take effect on restart; the rest hot-reload.");
+	return lines;
+};
+/**
 * Pure state-to-lines mapping, kept free of IO so it can be tested directly
 * without spawning a relay or opening a socket.
 */
 const renderStatus = (status$1) => {
 	const lines = [`copilot-relay ${status$1.version}`];
 	if (!status$1.running) {
-		lines.push("  process    not running", `  config     ${status$1.configPath} (logLevel=${status$1.logLevel}, thinkEffort=${status$1.thinkEffort})`, `  log        ${status$1.logPath}`, "", "  Start it with: copilot-relay start");
+		lines.push("  process    not running", `  log        ${status$1.logPath}`, `  config     ${status$1.configPath}`, ...renderConfig(status$1.config, false), "", "  Start it with: copilot-relay start");
 		return lines;
 	}
 	lines.push(`  process    running (pid ${status$1.pid}, up ${formatUptime(status$1.startedAt)})`);
@@ -3371,7 +3648,7 @@ const renderStatus = (status$1) => {
 	lines.push(status$1.models?.length ? `  models     ${status$1.models.join(", ")}` : "  models     unavailable");
 	if (status$1.deep) lines.push(status$1.deep.ok ? `  upstream   ok (${status$1.deep.ms}ms) — end-to-end Copilot round trip` : `  upstream   FAILED${status$1.deep.detail ? ` — ${status$1.deep.detail}` : ""}`);
 	else lines.push("  upstream   not checked (use --deep)");
-	lines.push(`  log        ${status$1.logPath}`, `  config     ${status$1.configPath} (logLevel=${status$1.logLevel}, thinkEffort=${status$1.thinkEffort})`);
+	lines.push(`  log        ${status$1.logPath}`, `  config     ${status$1.configPath}`, ...renderConfig(status$1.config, true));
 	if (status$1.health?.ok && status$1.deep && !status$1.deep.ok) lines.push("", "  The relay is listening but cannot reach Copilot.", "  Try: copilot-relay auth");
 	if (hasVersionMismatch(status$1)) lines.push("", `  The running relay is ${status$1.daemonVersion}; ${status$1.version} is installed.`, "  Restart it to serve the installed version: copilot-relay restart");
 	return lines;
@@ -3478,7 +3755,9 @@ const checkDeep = async (baseUrl, model) => {
 const collectStatus = async (options) => {
 	const appConfig = await readAppConfig();
 	setLogLevel(appConfig.logLevel);
+	registerSensitiveOrigin(appConfig.copilotBaseUrl);
 	const base = {
+		config: toStatusConfig(appConfig),
 		configPath: paths.configPath,
 		logLevel: appConfig.logLevel,
 		logPath: getLogPath(),
@@ -3525,8 +3804,8 @@ const status = defineCommand({
 	},
 	async run({ args }) {
 		const result = await collectStatus({ deep: Boolean(args.deep) });
-		if (args.json) console.log(JSON.stringify(result, null, 2));
-		else console.log(renderStatus(result).join("\n"));
+		if (args.json) console.log(scrubSensitiveUrls(JSON.stringify(result, null, 2)));
+		else console.log(scrubSensitiveUrls(renderStatus(result).join("\n")));
 		process.exitCode = resolveExitCode(result);
 	}
 });