@athsra/cli 0.1.0 → 1.0.0

package/src/commands/completion.ts

@@ -0,0 +1,101 @@
+/**
+ * completion.ts — shell completion script 출력 (bash/zsh/fish).
+ *
+ * 사용:
+ *   athsra completion zsh  >> ~/.zshrc
+ *   athsra completion bash >> ~/.bashrc
+ *   athsra completion fish > ~/.config/fish/completions/athsra.fish
+ *
+ * 또는 1회용 source:
+ *   source <(athsra completion zsh)
+ *
+ * Phase 1.x.7 — Doppler 의 `doppler completion zsh|bash|fish` 동등 UX.
+ * 19 commands subcommand 기본 complete. sub-options (--from-file 등) 은 별 chunk.
+ */
+
+interface CommandSpec {
+  name: string;
+  desc: string;
+}
+
+const COMMANDS: CommandSpec[] = [
+  { name: 'login', desc: 'master pw 입력 + 머신 등록 (Bearer token 발급)' },
+  { name: 'logout', desc: 'keyring clear (worker token 유지). --full 시 config 도 삭제' },
+  { name: 'init', desc: '신규 project 안내 (실 생성은 첫 set 시)' },
+  { name: 'set', desc: 'secret 추가/수정 (다건, --from-file, --stdin 지원)' },
+  { name: 'unset', desc: '특정 key 제거 (envelope 유지)' },
+  { name: 'get', desc: '값 출력 (single 또는 dump)' },
+  { name: 'ls', desc: 'project 또는 key 목록 (--all=deleted 포함)' },
+  { name: 'run', desc: 'env inject 후 명령 실행 (Doppler-style)' },
+  { name: 'doctor', desc: '환경 검증 (keyring/dbus/worker phase)' },
+  { name: 'versions', desc: '모든 version + tombstone 상태' },
+  { name: 'rollback', desc: '특정 version 으로 current 복원' },
+  { name: 'delete', desc: 'soft-delete (default) 또는 --hard' },
+  { name: 'restore', desc: 'tombstone 제거 + 최신 version 활성화' },
+  { name: 'purge', desc: 'hard-delete 별칭 (double-confirm)' },
+  { name: 'rotate-master', desc: 'master pw 변경 (모든 projects re-encrypt)' },
+  { name: 'new-phrase', desc: 'BIP-39 12-word phrase 생성' },
+  { name: 'handoff', desc: '새 머신 추가 (issue / --accept)' },
+  { name: 'revoke', desc: 'self 또는 명시 token revoke' },
+  { name: 'completion', desc: 'shell completion script 출력' },
+];
+
+function bashCompletion(): string {
+  const names = COMMANDS.map((c) => c.name).join(' ');
+  return `# athsra bash completion — generated by 'athsra completion bash'
+_athsra_complete() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${names} --version --help" -- "$cur") )
+  fi
+}
+complete -F _athsra_complete athsra
+`;
+}
+
+function zshCompletion(): string {
+  const lines = COMMANDS.map((c) => `    '${c.name}:${c.desc.replace(/'/g, "''")}'`).join('\n');
+  return `#compdef athsra
+# athsra zsh completion — generated by 'athsra completion zsh'
+_athsra() {
+  local -a _athsra_cmds
+  _athsra_cmds=(
+${lines}
+    '--version:print version'
+    '--help:print help'
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' _athsra_cmds
+  fi
+}
+compdef _athsra athsra
+`;
+}
+
+function fishCompletion(): string {
+  return COMMANDS.map(
+    (c) =>
+      `complete -c athsra -n "__fish_use_subcommand" -a "${c.name}" -d "${c.desc.replace(/"/g, '\\"')}"`,
+  )
+    .join('\n')
+    .concat('\n');
+}
+
+export async function completionCmd(args: string[]): Promise<number> {
+  const shell = args[0];
+  if (!shell || (shell !== 'bash' && shell !== 'zsh' && shell !== 'fish')) {
+    console.error('usage: athsra completion {bash|zsh|fish}');
+    console.error('');
+    console.error('  Append to your shell rc:');
+    console.error('    bash: athsra completion bash >> ~/.bashrc');
+    console.error(
+      '    zsh:  athsra completion zsh  >> ~/.zshrc   (또는 ~/.zsh/completions/_athsra)',
+    );
+    console.error('    fish: athsra completion fish > ~/.config/fish/completions/athsra.fish');
+    return 2;
+  }
+  if (shell === 'bash') console.log(bashCompletion());
+  else if (shell === 'zsh') console.log(zshCompletion());
+  else console.log(fishCompletion());
+  return 0;
+}

package/src/commands/delete.ts

@@ -22,7 +22,7 @@ export async function deleteCmd(args: string[]): Promise<number> {
   const hard = args.includes('--hard');
   const yes = args.includes('--yes') || args.includes('-y');
 
-  const ctx = loadAuthContext();
+  const ctx = await loadAuthContext();
   if (!ctx) return 1;
   const { client } = ctx;
 

package/src/commands/doctor.ts

@@ -1,9 +1,13 @@
 import { existsSync } from 'node:fs';
+import type { UserAuthContext } from '../lib/auth-context.ts';
 import { AthsraClient } from '../lib/client.ts';
 import { CONFIG_FILE, loadConfig, SESSION_FILE } from '../lib/config.ts';
+import { partitionEnv } from '../lib/env-format.ts';
+import { readPlain } from '../lib/envelope.ts';
 import { getMasterPw, getToken, probeKeyring } from '../lib/keyring.ts';
 
-export async function doctorCmd(_args: string[]): Promise<number> {
+export async function doctorCmd(args: string[]): Promise<number> {
+  const audit = args.includes('--audit');
   console.log('athsra doctor\n');
 
   const kr = probeKeyring();
@@ -49,6 +53,15 @@ export async function doctorCmd(_args: string[]): Promise<number> {
     if (info.phase < 1) {
       console.log('  ⚠ phase < 1 — Pre-A 인증 미배포 상태.');
     }
+    // Phase 1.x.5: GLOBAL_SALT_VERSION change 감지
+    if (info.proof_invalidated) {
+      console.log(
+        `  ⚠ PROOF invalidated — GLOBAL_SALT_VERSION 변경 감지 (PROOF: ${info.proof_global_salt_version} → worker: ${info.global_salt_version}).`,
+      );
+      console.log('     다음 `athsra login` 시 자동 재 register. R2 envelope 보존.');
+    } else if (info.proof_global_salt_version) {
+      console.log(`  proof_global_salt_version: ${info.proof_global_salt_version} (정상 일치)`);
+    }
   } catch (err) {
     console.log(`  info: error — ${(err as Error).message}`);
   }
@@ -72,5 +85,76 @@ export async function doctorCmd(_args: string[]): Promise<number> {
     }
   }
 
-  return kr.ok && reachable ? 0 : 1;
+  let auditFailed = false;
+  if (audit) {
+    if (!masterPw) {
+      console.log('\n  secret audit:     ✗ skipped — master-pw missing (run `athsra login`)');
+    } else if (!token) {
+      console.log('\n  secret audit:     ✗ skipped — token missing (run `athsra login`)');
+    } else {
+      const ctx: UserAuthContext = { kind: 'user', config, masterPw, token, client };
+      auditFailed = await runSecretAudit(ctx);
+    }
+  }
+
+  return kr.ok && reachable && !auditFailed ? 0 : 1;
+}
+
+/**
+ * `athsra doctor --audit` — 전 active project 를 decrypt 해 빈 값 키를 전수 점검한다.
+ *
+ * Issue 3: 2026-05-10 secret migration 이 키 이름만 scaffolding 하고 값 입력을
+ * 누락해 여러 project 가 빈 값 키를 갖게 됐다 (ecosystem.json 의 keysCount=0
+ * 기록과 불일치). worker 는 E2EE 라 plaintext 를 못 보므로 점검은 client-side.
+ *
+ * @returns true = 빈 값 키 또는 점검 오류 발견 (doctor exit code 에 반영)
+ */
+async function runSecretAudit(ctx: UserAuthContext): Promise<boolean> {
+  console.log('\n  secret audit (empty-value keys):');
+  let projects: string[];
+  try {
+    projects = await ctx.client.listProjects();
+  } catch (err) {
+    console.log(`    ✗ project list error — ${(err as Error).message}`);
+    return true;
+  }
+  if (projects.length === 0) {
+    console.log('    (no projects)');
+    return false;
+  }
+
+  let affected = 0;
+  let errored = 0;
+  for (const project of [...projects].sort()) {
+    try {
+      const plain = await readPlain(ctx, project);
+      if (!plain) {
+        console.log(`    ✗ ${project}: envelope missing`);
+        errored++;
+        continue;
+      }
+      const total = Object.keys(plain).length;
+      const { emptyKeys } = partitionEnv(plain);
+      if (emptyKeys.length > 0) {
+        affected++;
+        console.log(
+          `    ✗ ${project}: ${emptyKeys.length}/${total} empty — ${emptyKeys.join(', ')}`,
+        );
+      } else {
+        console.log(`    ✓ ${project}: ${total} key${total === 1 ? '' : 's'}, all set`);
+      }
+    } catch (err) {
+      errored++;
+      console.log(`    ✗ ${project}: decrypt error — ${(err as Error).message}`);
+    }
+  }
+
+  if (affected > 0) {
+    console.log(
+      `\n  ⚠ ${affected} project${affected === 1 ? '' : 's'} with empty-value keys — deploy auth fails until real values are set (\`athsra set <project> KEY=value\`).`,
+    );
+  } else if (errored === 0) {
+    console.log('\n  ✓ all projects: every key has a non-empty value.');
+  }
+  return affected > 0 || errored > 0;
 }

package/src/commands/get.ts

@@ -1,6 +1,6 @@
-import { decrypt, deriveKey, fromBase64 } from '@athsra/crypto';
 import { loadAuthContext } from '../lib/auth-context.ts';
-import { parseEnv } from '../lib/env-format.ts';
+import { serializeEnv } from '../lib/env-format.ts';
+import { readPlain } from '../lib/envelope.ts';
 
 export async function getCmd(args: string[]): Promise<number> {
   const project = args[0];
@@ -10,31 +10,27 @@ export async function getCmd(args: string[]): Promise<number> {
     return 2;
   }
 
-  const ctx = loadAuthContext();
+  const ctx = await loadAuthContext();
   if (!ctx) return 1;
-  const { masterPw, client } = ctx;
-  const envelope = await client.getEnvelope(project);
-  if (!envelope) {
+
+  const plain = await readPlain(ctx, project);
+  if (!plain) {
     console.error(`project not found: ${project}`);
     return 1;
   }
 
-  const derived = deriveKey(masterPw, fromBase64(envelope.salt));
-  const text = await decrypt(derived, {
-    ciphertext: fromBase64(envelope.ciphertext),
-    nonce: fromBase64(envelope.nonce),
-  });
-
   if (key) {
-    const plain = parseEnv(text);
     const value = plain[key];
     if (value === undefined) {
       console.error(`key not found: ${key}`);
       return 1;
     }
+    if (value === '') {
+      console.error(`warning: ${key} has an empty value (treated as unset by \`athsra run\`)`);
+    }
     console.log(value);
   } else {
-    console.log(text);
+    console.log(serializeEnv(plain));
   }
   return 0;
 }

package/src/commands/handoff.ts

@@ -1,8 +1,9 @@
 import { hostname } from 'node:os';
 import { deriveKey, fromBase64, toBase64 } from '@athsra/crypto';
-import { loadAuthContext } from '../lib/auth-context.ts';
+import { loadAuthContext, type UserAuthContext } from '../lib/auth-context.ts';
 import { AthsraClient } from '../lib/client.ts';
 import { type Config, saveConfig } from '../lib/config.ts';
+import { readPlain } from '../lib/envelope.ts';
 import { probeKeyring, setMasterPw, setToken } from '../lib/keyring.ts';
 import { promptPassword, promptText } from '../lib/prompt.ts';
 
@@ -13,8 +14,12 @@ const USAGE = [
 
 async function issueToken(): Promise<number> {
   console.log('athsra handoff (issue, 기존 머신에서)\n');
-  const ctx = loadAuthContext();
+  const ctx = await loadAuthContext();
   if (!ctx) return 1;
+  if (ctx.kind !== 'user') {
+    console.error('athsra handoff 은 user token (master pw) 가 필요합니다.');
+    return 1;
+  }
   const { masterPw, client } = ctx;
 
   const newLabel = await promptText('New machine label (예: home-desktop)');
@@ -89,23 +94,22 @@ async function acceptToken(): Promise<number> {
     return 1;
   }
 
-  // master pw 검증: 첫 envelope (있으면) decrypt 시도
+  // master pw 검증: 첫 envelope (있으면) decrypt 시도 (v1/v2 dispatcher)
   const projects = await client.listProjects();
   const first = projects[0];
   if (first) {
-    const env = await client.getEnvelope(first);
-    if (env) {
-      try {
-        const key = deriveKey(masterPw, fromBase64(env.salt));
-        const { decrypt } = await import('@athsra/crypto');
-        await decrypt(key, {
-          ciphertext: fromBase64(env.ciphertext),
-          nonce: fromBase64(env.nonce),
-        });
-      } catch {
-        console.error('✗ master password mismatch — 옛 master pw 와 일치 X');
-        return 1;
-      }
+    const tempCtx: UserAuthContext = {
+      kind: 'user',
+      config: { workerUrl, machineId, createdAt: me.createdAt },
+      masterPw,
+      token,
+      client,
+    };
+    try {
+      await readPlain(tempCtx, first);
+    } catch {
+      console.error('✗ master password mismatch — 옛 master pw 와 일치 X');
+      return 1;
     }
   }
 

package/src/commands/login.ts

@@ -1,3 +1,6 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 import { hostname } from 'node:os';
 import { deriveKey, fromBase64, toBase64 } from '@athsra/crypto';
 import { isValidPhrase, normalizePhrase, wordCount } from '../lib/bip39.ts';
@@ -7,7 +10,298 @@ import { probeKeyring, setMasterPw, setToken } from '../lib/keyring.ts';
 import { consumeLegacySession } from '../lib/legacy-session.ts';
 import { promptConfirm, promptPassword, promptText } from '../lib/prompt.ts';
 
-export async function loginCmd(_args: string[]): Promise<number> {
+/**
+ * Phase 2.8 (2026-05-26) — Connect SSO 로그인 (OIDC PKCE).
+ *
+ * 흐름:
+ *   1) PKCE code_verifier + challenge 생성
+ *   2) localhost callback HTTP server start (ephemeral port)
+ *   3) browser open → Connect /authorize
+ *   4) callback ?code= → POST Connect /token (code + verifier) → access_token
+ *   5) POST worker /auth/sso (access_token + label) → athsra Bearer token
+ *   6) keyring 저장 + master pw prompt (envelope decrypt 용)
+ *
+ * E2EE 정합: SSO 는 worker 인증 layer 만. master pw 는 envelope decrypt 전용.
+ */
+
+const SSO_DEFAULTS = {
+  /** Connect authorize endpoint */
+  authorizeUrl: 'https://login.modfolio.io/authorize',
+  /** Connect token endpoint */
+  tokenUrl: 'https://login.modfolio.io/token',
+  /** Connect 측 CLI client (PKCE public, no secret). 사용자가 별도 등록. */
+  clientId: 'athsra-cli',
+  /** OIDC scope */
+  scope: 'openid profile email',
+  /** callback timeout (ms) — 사용자 browser 작업 대기 */
+  callbackTimeoutMs: 5 * 60 * 1000,
+};
+
+interface CallbackResult {
+  code: string;
+  state: string;
+}
+
+/** Start ephemeral loopback HTTP callback server. Closes after first valid callback or timeout. */
+async function waitForCallback(
+  expectedState: string,
+  port: number,
+  timeoutMs: number,
+): Promise<CallbackResult> {
+  return await new Promise<CallbackResult>((resolve, reject) => {
+    const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+      if (url.pathname !== '/callback') {
+        res.statusCode = 404;
+        res.end('not found');
+        return;
+      }
+      const code = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+      const error = url.searchParams.get('error');
+      if (error) {
+        res.statusCode = 400;
+        res.end(`Authorization failed: ${error}. Return to terminal.`);
+        server.close();
+        reject(new Error(`Connect authorize error: ${error}`));
+        return;
+      }
+      if (!code || !state) {
+        res.statusCode = 400;
+        res.end('Missing code or state. Return to terminal.');
+        server.close();
+        reject(new Error('Missing code or state in callback'));
+        return;
+      }
+      if (state !== expectedState) {
+        res.statusCode = 400;
+        res.end('State mismatch — possible CSRF. Return to terminal.');
+        server.close();
+        reject(new Error('State mismatch'));
+        return;
+      }
+      res.statusCode = 200;
+      res.setHeader('content-type', 'text/html; charset=utf-8');
+      res.end(
+        '<!doctype html><html><body style="font-family:system-ui;padding:2rem;">' +
+          '<h2>✓ athsra SSO 로그인 완료</h2>' +
+          '<p>터미널로 돌아가세요. 이 창은 닫아도 됩니다.</p>' +
+          '</body></html>',
+      );
+      server.close();
+      resolve({ code, state });
+    });
+    server.listen(port, '127.0.0.1');
+    setTimeout(() => {
+      server.close();
+      reject(new Error(`callback timeout after ${timeoutMs / 1000}s`));
+    }, timeoutMs);
+  });
+}
+
+function base64urlBuf(buf: Buffer): string {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function openBrowser(url: string): void {
+  const platform = process.platform;
+  const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+}
+
+async function findFreePort(): Promise<number> {
+  // 49152-65535 ephemeral range. createServer port=0 자동 할당.
+  return await new Promise<number>((resolve, reject) => {
+    const server = createServer();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (typeof address !== 'object' || address === null) {
+        server.close();
+        reject(new Error('no port'));
+        return;
+      }
+      const port = address.port;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+async function ssoLoginCmd(): Promise<number> {
+  console.log('athsra login --sso (modfolio-connect OIDC PKCE)\n');
+
+  // 1. keyring backend
+  const probe = probeKeyring();
+  if (!probe.ok) {
+    console.error(`✗ keyring backend unavailable: ${probe.error ?? 'unknown'}`);
+    return 1;
+  }
+
+  // 2. config — workerUrl + machineId
+  const existing = loadConfig();
+  const envUrl = process.env.ATHSRA_WORKER_URL;
+  const workerUrl =
+    existing?.workerUrl ??
+    envUrl ??
+    (await promptText('Worker URL', 'https://athsra-worker.winterermod.workers.dev'));
+  const machineId = existing?.machineId ?? `${hostname()}-${Date.now().toString(36)}`;
+
+  // 3. worker reachability
+  const tempClient = new AthsraClient(workerUrl);
+  const reachable = await tempClient.health();
+  if (!reachable) {
+    console.error(`✗ worker unreachable: ${workerUrl}`);
+    return 1;
+  }
+
+  // 4. PKCE + state 생성
+  const codeVerifier = base64urlBuf(randomBytes(48));
+  const codeChallenge = base64urlBuf(createHash('sha256').update(codeVerifier).digest());
+  const state = base64urlBuf(randomBytes(16));
+
+  // 5. callback server start
+  let port: number;
+  try {
+    port = await findFreePort();
+  } catch (err) {
+    console.error(`✗ cannot allocate callback port: ${(err as Error).message}`);
+    return 1;
+  }
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  // 6. browser open
+  const authorizeUrl = process.env.ATHSRA_SSO_AUTHORIZE_URL ?? SSO_DEFAULTS.authorizeUrl;
+  const clientId = process.env.ATHSRA_SSO_CLIENT_ID ?? SSO_DEFAULTS.clientId;
+  const params = new URLSearchParams({
+    client_id: clientId,
+    response_type: 'code',
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+    state,
+    redirect_uri: redirectUri,
+    scope: SSO_DEFAULTS.scope,
+  });
+  const authUrl = `${authorizeUrl}?${params.toString()}`;
+  console.log(`opening browser: ${authUrl.slice(0, 80)}...`);
+  console.log(`callback: ${redirectUri}`);
+  console.log('(complete login in browser — terminal will resume when callback received)\n');
+  openBrowser(authUrl);
+
+  // 7. wait for callback
+  let callback: CallbackResult;
+  try {
+    callback = await waitForCallback(state, port, SSO_DEFAULTS.callbackTimeoutMs);
+  } catch (err) {
+    console.error(`✗ callback failed: ${(err as Error).message}`);
+    return 1;
+  }
+  console.log('✓ callback received, exchanging code...');
+
+  // 8. token exchange (Connect /token)
+  const tokenUrl = process.env.ATHSRA_SSO_TOKEN_URL ?? SSO_DEFAULTS.tokenUrl;
+  const tokenRes = await fetch(tokenUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'authorization_code',
+      code: callback.code,
+      code_verifier: codeVerifier,
+      client_id: clientId,
+      redirect_uri: redirectUri,
+    }).toString(),
+  });
+  if (!tokenRes.ok) {
+    console.error(`✗ Connect token exchange failed: ${tokenRes.status} ${await tokenRes.text()}`);
+    return 1;
+  }
+  const tokenBody = (await tokenRes.json()) as { access_token?: string };
+  if (!tokenBody.access_token) {
+    console.error('✗ Connect token response missing access_token');
+    return 1;
+  }
+  console.log('✓ Connect access_token received');
+
+  // 9. worker /auth/sso (Connect token → athsra Bearer)
+  const ssoRes = await fetch(`${workerUrl}/auth/sso`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ access_token: tokenBody.access_token, label: machineId }),
+  });
+  if (!ssoRes.ok) {
+    console.error(`✗ athsra worker SSO failed: ${ssoRes.status} ${await ssoRes.text()}`);
+    return 1;
+  }
+  const ssoBody = (await ssoRes.json()) as {
+    token: string;
+    identifier: string;
+    expires_at?: string;
+    createdAt: string;
+  };
+
+  // 10. master pw prompt (envelope decrypt 전용 — worker 에 송신 X)
+  console.log('\n● Master password — envelope decrypt (E2EE, worker 노출 X)');
+  const envPw = process.env.ATHSRA_MASTER_PW;
+  let masterPw: string;
+  if (envPw && envPw.length >= 8) {
+    masterPw = envPw;
+    console.log('• Master password from $ATHSRA_MASTER_PW (non-interactive).');
+  } else {
+    masterPw = await promptPassword('Master password (8+ chars)');
+    if (masterPw.length < 8) {
+      console.error('Master password must be at least 8 characters');
+      return 1;
+    }
+  }
+  if (isValidPhrase(masterPw)) {
+    const wc = wordCount(masterPw);
+    console.log(`• Master password is a valid BIP-39 ${wc}-word phrase ✓`);
+    masterPw = normalizePhrase(masterPw);
+  }
+
+  // 11. config + keyring 저장
+  const config: Config = {
+    workerUrl,
+    machineId,
+    createdAt: existing?.createdAt ?? ssoBody.createdAt,
+  };
+  saveConfig(config);
+  setMasterPw(machineId, masterPw);
+  setToken(machineId, ssoBody.token);
+
+  console.log(`\n✓ SSO logged in (machine: ${machineId})`);
+  console.log(`  identifier: ${ssoBody.identifier}`);
+  console.log(`  worker:     ${workerUrl}`);
+  if (ssoBody.expires_at) {
+    console.log(`  expires:    ${ssoBody.expires_at}`);
+  }
+  console.log('  keyring:    master-pw + token saved (OS keyring)');
+  return 0;
+}
+
+const LOGIN_USAGE = [
+  'usage: athsra login [--sso]',
+  '',
+  '기본 (master pw + paper backup): athsra login',
+  'SSO (modfolio-connect OIDC PKCE — Phase 2.8): athsra login --sso',
+  '',
+  '환경변수:',
+  '  ATHSRA_WORKER_URL           worker URL (config 우선)',
+  '  ATHSRA_MASTER_PW            non-interactive master pw',
+  '  ATHSRA_PAPER_BACKUP_CONFIRMED=1   paper-backup prompt 우회',
+  '  ATHSRA_SSO_AUTHORIZE_URL    Connect /authorize override',
+  '  ATHSRA_SSO_TOKEN_URL        Connect /token override',
+  '  ATHSRA_SSO_CLIENT_ID        Connect client_id (default: athsra-cli)',
+].join('\n');
+
+export async function loginCmd(args: string[]): Promise<number> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(LOGIN_USAGE);
+    return 0;
+  }
+  if (args.includes('--sso')) {
+    return ssoLoginCmd();
+  }
   console.log('athsra login\n');
 
   // 1. keyring backend probe (정공법: fallback 없음)
@@ -102,6 +396,17 @@ export async function loginCmd(_args: string[]): Promise<number> {
     return 1;
   }
 
+  // Phase 1.x.5: GLOBAL_SALT_VERSION change 감지 안내
+  if (info.proof_invalidated) {
+    console.log('');
+    console.log(
+      `⚠ GLOBAL_SALT_VERSION 변경 감지 (PROOF: ${info.proof_global_salt_version} → worker: ${info.global_salt_version}).`,
+    );
+    console.log('  옛 PROOF 가 다음 register 시 자동 invalidate 됩니다.');
+    console.log('  R2 envelope 은 영향 없습니다 (per-envelope salt 사용 — secret data 보존).');
+    console.log('  동일 master password 로 재 register 진행합니다.\n');
+  }
+
   // 7. master_pw_proof = Argon2id(pw + GLOBAL_SALT)
   const proofBytes = deriveKey(masterPw, fromBase64(info.global_salt));
   const proofBase64 = toBase64(proofBytes);