@ait-co/console-cli 0.1.36 → 0.1.37

package/README.en.md

@@ -111,6 +111,43 @@ Pass `--interactive` to force the visible-browser flow even when credentials are
 
 The CLI looks for Chrome in the standard OS install locations (Google Chrome, Chromium, Microsoft Edge). Override the executable with `AITCC_BROWSER=/path/to/chrome` if your install is elsewhere; override the sign-in URL with `AITCC_OAUTH_URL` if you need to point at a staging environment. `--timeout <seconds>` controls how long the CLI will wait for sign-in to finish (default 300s).
 
+## Using aitcc in SSH / headless environments
+
+macOS Keychain access is blocked in SSH remote sessions and GUI-less servers, so `--save keychain` will fail there. Three workarounds are available:
+
+**Option 1 — Export / import the session (recommended, requires a KR IP)**
+
+Export the session on a desktop GUI Mac and inject it into the SSH environment:
+
+```sh
+# On a desktop Mac that is already logged in:
+aitcc auth export --format env   # outputs: AITCC_SESSION=...
+
+# In the SSH environment:
+AITCC_SESSION='...' aitcc app deploy ./bundle.ait --json
+```
+
+**Option 2 — Unlock the keychain**
+
+Unlock the keychain in the same SSH session, then retry:
+
+```sh
+security unlock-keychain ~/Library/Keychains/login.keychain-db
+# (enter login password when prompted)
+aitcc login --save keychain --email you@example.com --password-stdin
+```
+
+**Option 3 — File backend**
+
+Store credentials in a plain file instead of the keychain. Assumes a single-user machine; FileVault (full-disk encryption) is strongly recommended:
+
+```sh
+aitcc login --save=file --email you@example.com --password-stdin
+# → stored in ~/.config/aitcc/credentials.json (perm 0600)
+```
+
+After saving, subsequent `aitcc login` runs in the SSH environment will read this file and sign in headlessly. Override the path with the `AITCC_CREDENTIAL_FILE` environment variable. See [issue #176](https://github.com/apps-in-toss-community/console-cli/issues/176) for background.
+
 ## Session storage
 
 The local session lives at an XDG-compliant path with file mode `0600`:

package/README.md

@@ -111,6 +111,43 @@ aitcc app status         # 플래그 없이 동작 — aitcc.yaml에서 컨텍
 
 CLI는 OS 표준 위치(Google Chrome, Chromium, Microsoft Edge)에서 Chrome을 찾습니다. 다른 곳에 설치돼 있으면 `AITCC_BROWSER=/path/to/chrome`으로 실행 파일을 지정하고, 스테이징 환경을 가리키려면 `AITCC_OAUTH_URL`로 로그인 URL을 override합니다. `--timeout <초>`로 로그인 대기 시간을 조절합니다 (기본 300초).
 
+## SSH / headless 환경에서 로그인
+
+SSH 원격 세션이나 GUI가 없는 서버에서는 macOS Keychain 접근이 막혀 `--save keychain`이 실패할 수 있습니다. 세 가지 우회 방법이 있습니다:
+
+**방법 1 — 세션 export/import (권장, KR IP 필요)**
+
+Desktop GUI Mac에서 세션을 export해 SSH 환경에 주입합니다:
+
+```sh
+# Desktop (GUI Mac, 이미 로그인된 상태):
+aitcc auth export --format env   # → AITCC_SESSION=... 출력
+
+# SSH 환경에서:
+AITCC_SESSION='...' aitcc app deploy ./bundle.ait --json
+```
+
+**방법 2 — keychain unlock**
+
+같은 SSH 세션에서 keychain을 잠금 해제한 뒤 재시도합니다:
+
+```sh
+security unlock-keychain ~/Library/Keychains/login.keychain-db
+# (login 비밀번호 입력)
+aitcc login --save keychain --email you@example.com --password-stdin
+```
+
+**방법 3 — 파일 backend**
+
+Keychain 대신 평문 파일에 자격증명을 저장합니다. 단일 사용자 머신 전제이며 FileVault(디스크 암호화) 사용을 권장합니다:
+
+```sh
+aitcc login --save=file --email you@example.com --password-stdin
+# → ~/.config/aitcc/credentials.json (perm 0600)에 저장
+```
+
+저장 후 SSH 환경에서 `aitcc login`이 자동으로 이 파일을 읽어 headless 로그인을 진행합니다. 경로를 바꾸려면 `AITCC_CREDENTIAL_FILE` env var를 지정합니다. 자세한 내용은 [issue #176](https://github.com/apps-in-toss-community/console-cli/issues/176) 참조.
+
 ## 세션 저장
 
 로컬 세션은 XDG 규약 경로에 mode `0600`으로 저장됩니다:

package/dist/cli.mjs

@@ -5913,6 +5913,74 @@ function redactStderr(stderr) {
 	return trimmed;
 }
 //#endregion
+//#region src/auth/backends/file.ts
+function credentialFilePath() {
+	const override = process.env.AITCC_CREDENTIAL_FILE;
+	if (override && override.length > 0) return override;
+	return join(configDir(), "credentials.json");
+}
+function makeKey(account) {
+	return `${CREDENTIAL_SERVICE}:${account}`;
+}
+async function readStore(filePath) {
+	let raw;
+	try {
+		raw = await readFile(filePath, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+	try {
+		const mode = (await stat(filePath)).mode & 511;
+		if (mode !== 384) process.stderr.write(`Warning: credential file ${filePath} has permissions ${mode.toString(8)} — expected 0600.\n  Run: chmod 600 ${filePath}\n`);
+	} catch {}
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+async function writeStore(filePath, store) {
+	await mkdir(dirname(filePath), {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(filePath, JSON.stringify(store, null, 2), { mode: 384 });
+	try {
+		await chmod(filePath, 384);
+	} catch {}
+}
+const FILE_BACKEND = {
+	name: "file",
+	async get(account) {
+		const store = await readStore(credentialFilePath());
+		if (store === null) return null;
+		const value = store[makeKey(account)];
+		return typeof value === "string" && value.length > 0 ? value : null;
+	},
+	async set(account, password) {
+		const filePath = credentialFilePath();
+		const store = await readStore(filePath) ?? {};
+		store[makeKey(account)] = password;
+		await writeStore(filePath, store);
+	},
+	async clear(account) {
+		const filePath = credentialFilePath();
+		const store = await readStore(filePath);
+		if (store === null) return { existed: false };
+		const key = makeKey(account);
+		if (!(key in store)) return { existed: false };
+		delete store[key];
+		if (Object.keys(store).length === 0) try {
+			await unlink(filePath);
+		} catch (err) {
+			if (err.code !== "ENOENT") throw err;
+		}
+		else await writeStore(filePath, store);
+		return { existed: true };
+	}
+};
+//#endregion
 //#region src/auth/backends/linux.ts
 const MISSING_HINT_FULL$1 = "libsecret tools are missing. Install `libsecret-tools` (Debian/Ubuntu) or the equivalent and ensure a Secret Service provider (gnome-keyring / KWallet) is running.";
 const MISSING_HINT_SHORT$1 = "libsecret tools are missing. Install `libsecret-tools` and ensure a Secret Service provider is running.";
@@ -6182,6 +6250,7 @@ if ($ok) { [Console]::Out.Write('deleted'); } else { [Console]::Out.Write('absen
 //#region src/auth/credentials.ts
 function resolveBackend(opts = {}) {
 	if (opts.override) return opts.override;
+	if (opts.useFile === true || process.env.AITCC_CREDENTIAL_BACKEND === "file") return FILE_BACKEND;
 	const platform = opts.platform ?? process.platform;
 	switch (platform) {
 		case "darwin": return MACOS_BACKEND;
@@ -6233,15 +6302,14 @@ async function clearAuthState() {
 /**
 * Resolve credentials from the highest-priority source available:
 *   1. `AITCC_EMAIL` + `AITCC_PASSWORD` env vars (CI single-shot use).
-*   2. OS keychain entry whose email is recorded in `auth-state.json`.
+*   2. File backend (`~/.config/aitcc/credentials.json`) when
+*      `AITCC_CREDENTIAL_BACKEND=file` is set or `opts.useFile` is true.
+*   3. OS keychain entry whose email is recorded in `auth-state.json`.
 *
 * Returns `null` when no source is configured. The discriminated `kind`
 * lets callers (e.g. the login flow) tell why a credential was found
 * without having to peek at process env themselves — useful for
 * "auto-login from CI" diagnostics.
-*
-* A future `'file'` source (~/.config/aitcc/credentials.json) is left as a
-* follow-up; once added, it slots between (1) and (2).
 */
 async function loadCredentials(opts = {}) {
 	const env = opts.env ?? process.env;
@@ -6254,10 +6322,11 @@ async function loadCredentials(opts = {}) {
 	};
 	const state = await readAuthState();
 	if (!state) return null;
-	const password = await resolveBackend(opts).get(state.activeEmail);
+	const backend = resolveBackend(opts);
+	const password = await backend.get(state.activeEmail);
 	if (password === null) return null;
 	return {
-		kind: "keychain",
+		kind: backend.name === "file" ? "file" : "keychain",
 		email: state.activeEmail,
 		password
 	};
@@ -6308,7 +6377,7 @@ async function getActiveCredentialEmail(opts = {}) {
 	const state = await readAuthState();
 	if (!state) return null;
 	return {
-		kind: "keychain",
+		kind: env.AITCC_CREDENTIAL_BACKEND === "file" ? "file" : "keychain",
 		email: state.activeEmail
 	};
 }
@@ -8095,13 +8164,20 @@ const defaultPromptDeps = {
 	saveTarget: () => select({
 		message: "Where would you like to save the credentials?",
 		default: "keychain",
-		choices: [{
-			name: "OS keychain (recommended) — next login runs headlessly",
-			value: "keychain"
-		}, {
-			name: "Do not save — one-shot. (Tip: AITCC_EMAIL/AITCC_PASSWORD env for CI.)",
-			value: "none"
-		}]
+		choices: [
+			{
+				name: "OS keychain (recommended) — next login runs headlessly",
+				value: "keychain"
+			},
+			{
+				name: "File (~/.config/aitcc/credentials.json, perm 0600) — use for SSH/headless sessions",
+				value: "file"
+			},
+			{
+				name: "Do not save — one-shot. (Tip: AITCC_EMAIL/AITCC_PASSWORD env for CI.)",
+				value: "none"
+			}
+		]
 	})
 };
 const loginCommand = defineCommand({
@@ -8140,7 +8216,7 @@ const loginCommand = defineCommand({
 		},
 		save: {
 			type: "string",
-			description: "Where to persist credentials when --email/--password* are passed: \"keychain\" or \"none\" (default)."
+			description: "Where to persist credentials when --email/--password* are passed: \"keychain\", \"file\", or \"none\" (default). Use \"file\" for SSH/headless sessions where the OS keychain is unavailable."
 		},
 		"skip-onboarding": {
 			type: "boolean",
@@ -8159,7 +8235,7 @@ const loginCommand = defineCommand({
 			save: typeof args.save === "string" ? args.save : void 0
 		}, {
 			getCredentials: loadCredentials,
-			saveCredentials
+			saveCredentials: (email, password, useFile) => saveCredentials(email, password, { useFile: useFile === true })
 		});
 	}
 });
@@ -8209,7 +8285,8 @@ async function runLoginCommand(args, deps) {
 		return exitAfterFlush(resolved.exitCode);
 	}
 	let saved = "skipped";
-	if (resolved.saveTarget === "keychain" && resolved.credentials !== null) {
+	if ((resolved.saveTarget === "keychain" || resolved.saveTarget === "file") && resolved.credentials !== null) {
+		const useFile = resolved.saveTarget === "file";
 		const save = deps.saveCredentials;
 		if (!save) {
 			emitError({
@@ -8219,16 +8296,25 @@ async function runLoginCommand(args, deps) {
 			return exitAfterFlush(ExitCode.Generic);
 		}
 		try {
-			const result = await save(resolved.credentials.email, resolved.credentials.password);
+			const result = await save(resolved.credentials.email, resolved.credentials.password, useFile);
 			saved = result.status;
 			if (!args.json) if (result.status === "unchanged") process.stderr.write("Credentials already saved (no change).\n");
+			else if (useFile) process.stderr.write(`Credentials saved to file backend (${resolved.credentials.email}).\n`);
 			else process.stderr.write(`Credentials saved to OS keychain (${resolved.credentials.email}).\n`);
 		} catch (err) {
 			const message = err.message;
-			emitError({
+			if (!useFile && process.platform === "darwin") emitError({
+				reason: "keychain-save-failed",
+				message
+			}, "keychain 접근에 실패했습니다.\nSSH/headless 세션이면 다음 중 하나를 시도하세요:\n  1) 데스크톱 GUI Mac에서: aitcc auth export --format=env (KR IP 필요)\n     SSH에서: AITCC_SESSION='...' aitcc auth import --from-env\n  2) 같은 SSH 세션에서 keychain unlock:\n     security unlock-keychain ~/Library/Keychains/login.keychain-db\n     (login 비밀번호 입력 후 재시도)\n  3) keychain 대신 파일 저장:\n     aitcc login --save=file (~/.config/aitcc/credentials.json, perm 0600)\n참고: https://github.com/apps-in-toss-community/console-cli/issues/176");
+			else if (!useFile) emitError({
 				reason: "keychain-save-failed",
 				message
 			}, `Failed to save credentials to the OS keychain: ${message}\nOn Linux, install libsecret (\`secret-tool\`) and retry. Re-run with \`--save none\` to skip persistence.`);
+			else emitError({
+				reason: "file-save-failed",
+				message
+			}, `Failed to save credentials to file backend: ${message}\nCheck that ~/.config/aitcc/ is writable, or use AITCC_CREDENTIAL_FILE to specify a custom path.`);
 			return exitAfterFlush(ExitCode.Usage);
 		}
 	}
@@ -8290,10 +8376,10 @@ async function resolveCredentialsForLogin(args, deps, opts = {}) {
 	};
 	let saveTarget;
 	if (args.save !== void 0) {
-		if (args.save !== "keychain" && args.save !== "none") return {
+		if (args.save !== "keychain" && args.save !== "file" && args.save !== "none") return {
 			kind: "error",
 			reason: "invalid-save",
-			message: `--save must be "keychain" or "none" (got "${args.save}").`,
+			message: `--save must be "keychain", "file", or "none" (got "${args.save}").`,
 			exitCode: ExitCode.Usage
 		};
 		saveTarget = args.save;
@@ -9338,7 +9424,7 @@ function resolveVersion() {
 		if (typeof injected === "string" && injected.length > 0) return injected;
 	} catch {}
 	try {
-		return "0.1.36";
+		return "0.1.37";
 	} catch {}
 	return "0.0.0-dev";
 }
@@ -10395,6 +10481,7 @@ async function describeCredentialSource() {
 function formatCredentials(cred) {
 	if (cred.source === "none") return "none (run `aitcc login` to save)";
 	if (cred.source === "env") return `env (AITCC_EMAIL${cred.email ? ` = ${cred.email}` : ""})`;
+	if (cred.source === "file") return `file (~/.config/aitcc/credentials.json)${cred.email ? ` (${cred.email})` : ""}`;
 	return `keychain${cred.email ? ` (${cred.email})` : ""}`;
 }
 async function runBackgroundUpdateCheck(json) {