@athsra/cli 1.0.2 → 1.0.4

package/src/lib/envelope.ts

@@ -16,16 +16,66 @@ import {
   decryptEnvelopeV2,
   deriveKey,
   fromBase64,
+  type KDFParams,
+  reEncryptEnvelopeBody,
   type SecretEnvelopeAny,
   type SecretEnvelopeV2,
 } from '@athsra/crypto';
-import type { AuthContext } from './auth-context.ts';
+import {
+  decryptEnvelopeAsMember,
+  reEncryptAsMember,
+  unwrapPrivateKey,
+} from '@athsra/crypto/member';
+import type { AuthContext, UserAuthContext } from './auth-context.ts';
 import { parseEnv, serializeEnv } from './env-format.ts';
 
+/**
+ * Slice 6c — owner master pw 가 아닌 멤버(admin role)의 X25519 private key 를 fetch+unwrap.
+ * GET /auth/keys 의 wrapped privkey 를 자기 master pw 로 푼다 (worker 는 평문 privkey 못 봄).
+ * 키 없거나 pw 불일치면 null.
+ */
+async function memberPrivateKey(ctx: UserAuthContext): Promise<Uint8Array | null> {
+  const keyRow = await ctx.client.getKeys();
+  if (!keyRow) return null;
+  try {
+    return await unwrapPrivateKey(
+      {
+        wrappedPrivateKey: keyRow.wrapped_private_key,
+        keySalt: keyRow.key_salt,
+        wrapNonce: keyRow.wrap_nonce,
+        kdfParams: keyRow.kdf_params,
+      },
+      ctx.masterPw,
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** env 에 내 member recipient 가 있으면 내 userId 반환 (member 경로 자격). 아니면 null. */
+async function memberRecipientUserId(
+  env: SecretEnvelopeV2,
+  ctx: UserAuthContext,
+): Promise<number | null> {
+  const me = await ctx.client.whoami();
+  if (me.userId === undefined) return null;
+  return env.recipients.some((r) => r.id === `member:${me.userId}`) ? me.userId : null;
+}
+
 async function decryptEnvelope(env: SecretEnvelopeAny, ctx: AuthContext): Promise<string> {
   if (ctx.kind === 'user') {
     if (env.version === 2) {
-      return decryptEnvelopeV2(env, ctx.masterPw, 'master');
+      try {
+        return await decryptEnvelopeV2(env, ctx.masterPw, 'master');
+      } catch (masterErr) {
+        // Slice 6c — master(owner) 복호 실패: 내가 member recipient 면 내 X25519 키로 복호
+        // (org 공유 시크릿을 owner master pw 없이). 멤버 아니면 원 에러(잘못된 master pw).
+        const memberUserId = await memberRecipientUserId(env, ctx);
+        if (memberUserId === null) throw masterErr;
+        const priv = await memberPrivateKey(ctx);
+        if (!priv) throw masterErr;
+        return decryptEnvelopeAsMember(env, priv, memberUserId);
+      }
     }
     const key = deriveKey(ctx.masterPw, fromBase64(env.salt), env.kdf_params);
     return decrypt(key, {
@@ -66,11 +116,47 @@ export async function writePlain(
   ctx: AuthContext,
   project: string,
   plain: Record<string, string>,
+  opts?: { kdfParams?: KDFParams },
 ): Promise<SecretEnvelopeV2> {
   if (ctx.kind !== 'user') {
     throw new Error('service token cannot write envelopes — use a user token (master pw)');
   }
-  const env = await createEnvelopeV2(serializeEnv(plain), ctx.masterPw);
+  const serialized = serializeEnv(plain);
+
+  // opts.kdfParams 명시 = rotate-master 의 의도적 reset (ENTERPRISE_KDF 마이그레이션):
+  // 새 envelope 를 만들어 모든 service recipient 를 의도적으로 폐기 (master pw 재확립
+  // = scoped 신뢰 reset). routine write 와 구분되는 유일한 신호.
+  if (opts?.kdfParams) {
+    const env = await createEnvelopeV2(serialized, ctx.masterPw, { kdfParams: opts.kdfParams });
+    await ctx.client.putEnvelope(project, env);
+    return env;
+  }
+
+  // routine write (set/unset/mcp/sync): 기존 v2 envelope 가 있으면 본문만 재암호화해
+  // kdf_params 와 모든 recipient (service token 포함) 를 보존한다. createEnvelopeV2 로
+  // 새로 만들면 service recipient 가 silent 삭제되고 kdf 가 DEFAULT(64MB) 로 downgrade 됨.
+  const existing = await ctx.client.getEnvelope(project);
+  if (existing && existing.version === 2) {
+    try {
+      const env = await reEncryptEnvelopeBody(existing, ctx.masterPw, serialized);
+      await ctx.client.putEnvelope(project, env);
+      return env;
+    } catch (masterErr) {
+      // Slice 6c — master(owner) 가 아니면 member 경로: 내 X25519 키로 DEK 얻어 본문만 재암호
+      // (recipients 보존 — server recipient-continuity 가 body-only 로 허용). 멤버 아니면 원 에러.
+      const memberUserId = await memberRecipientUserId(existing, ctx);
+      if (memberUserId === null) throw masterErr;
+      const priv = await memberPrivateKey(ctx);
+      if (!priv) throw masterErr;
+      const env = await reEncryptAsMember(existing, priv, memberUserId, serialized);
+      await ctx.client.putEnvelope(project, env);
+      return env;
+    }
+  }
+
+  // 신규 프로젝트 또는 v1 (recipients[] 없음) → 새 v2 (DEFAULT_KDF). v1 의 enterprise
+  // 마이그레이션은 rotate-master / service-token create (migrateV1ToV2) 경로가 담당.
+  const env = await createEnvelopeV2(serialized, ctx.masterPw);
   await ctx.client.putEnvelope(project, env);
   return env;
 }

package/src/lib/identity-key.ts

@@ -0,0 +1,59 @@
+/**
+ * identity-key.ts — Phase 4 Slice 3 CLI 측 X25519 identity 키쌍 provisioning/rotation.
+ *
+ * login 시 키쌍이 없으면 생성(ensureKeypair) + master pw 로 wrap 해 server 에 저장(평문 privkey·
+ * pw 는 server 미노출). rotate-master 시 기존 privkey 를 새 pw 로 재포장(rewrapForRotation).
+ * crypto 는 @athsra/crypto/member (subpath — worker 번들 격리).
+ */
+import { toBase64 } from '@athsra/crypto';
+import { generateIdentityKeypair, unwrapPrivateKey, wrapPrivateKey } from '@athsra/crypto/member';
+import type { AthsraClient, IdentityKeyRewrap } from './client.ts';
+
+/**
+ * identity 키쌍 보장 (멱등). 이미 있으면 no-op, 없으면 생성 + wrap + POST. login(register/SSO)
+ * 직후 호출. 실패해도 login 자체는 성공으로 두되 호출측이 경고 — 키쌍은 다음 login 에 재시도된다
+ * (provisioning 은 best-effort substrate, 실제 공유는 Slice 6).
+ */
+export async function ensureKeypair(client: AthsraClient, masterPw: string): Promise<boolean> {
+  const existing = await client.getKeys();
+  if (existing) return false;
+  const kp = generateIdentityKeypair();
+  const wrapped = await wrapPrivateKey(kp.privateKey, masterPw);
+  await client.setKeys({
+    public_key: toBase64(kp.publicKey),
+    wrapped_private_key: wrapped.wrappedPrivateKey,
+    key_salt: wrapped.keySalt,
+    wrap_nonce: wrapped.wrapNonce,
+    kdf_params: wrapped.kdfParams,
+  });
+  return true;
+}
+
+/**
+ * rotate-master 용 — 기존 identity privkey 를 old pw 로 unwrap → new pw 로 재포장한 재료(없으면
+ * null). pubkey 불변. rotateMaster body 로 전달돼 proof 회전과 원자적으로 갱신된다.
+ */
+export async function rewrapForRotation(
+  client: AthsraClient,
+  oldPw: string,
+  newPw: string,
+): Promise<IdentityKeyRewrap | null> {
+  const existing = await client.getKeys();
+  if (!existing) return null;
+  const privateKey = await unwrapPrivateKey(
+    {
+      wrappedPrivateKey: existing.wrapped_private_key,
+      keySalt: existing.key_salt,
+      wrapNonce: existing.wrap_nonce,
+      kdfParams: existing.kdf_params,
+    },
+    oldPw,
+  );
+  const rewrapped = await wrapPrivateKey(privateKey, newPw);
+  return {
+    wrapped_private_key: rewrapped.wrappedPrivateKey,
+    key_salt: rewrapped.keySalt,
+    wrap_nonce: rewrapped.wrapNonce,
+    kdf_params: rewrapped.kdfParams,
+  };
+}

package/src/lib/keyring.ts

@@ -46,6 +46,32 @@ export function clearToken(machineId: string): void {
   }
 }
 
+/**
+ * Phase 3 P3 (2026-05-31) — device-login 으로 발급된 project-scoped service token (ats_*).
+ *
+ * machine 전역의 user token (master-pw + token) 과 별개. 비-TTY agent 가 master pw 없이
+ * `athsra run <project>` 하도록, project 별 slot 에 저장. loadAuthContext(project) 가 조회.
+ */
+export function setDeviceToken(project: string, token: string): void {
+  entry(`device-token:${project}`).setPassword(token);
+}
+
+export function getDeviceToken(project: string): string | null {
+  try {
+    return entry(`device-token:${project}`).getPassword();
+  } catch {
+    return null;
+  }
+}
+
+export function clearDeviceToken(project: string): void {
+  try {
+    entry(`device-token:${project}`).deletePassword();
+  } catch {
+    /* ignore */
+  }
+}
+
 export interface ProbeResult {
   ok: boolean;
   error?: string;

package/src/lib/mcp-tools/args.ts

@@ -0,0 +1,60 @@
+/**
+ * mcp-tools/args.ts — MCP tool 인자 파싱 + worker 선택 헬퍼.
+ *
+ * `commands/mcp.ts` 에서 분리 (2026-06-02 리팩토링). read/write 핸들러 공용. 동작 보존.
+ */
+
+import type { WrangerWorker } from '../adopt-context.ts';
+
+export function pickWorker(
+  workers: WrangerWorker[],
+  explicit?: string,
+): WrangerWorker | { error: string } {
+  if (explicit) {
+    const found = workers.find((w) => w.name === explicit);
+    if (found) return found;
+    const names = workers.map((w) => w.name).join(', ') || '(none)';
+    return { error: `worker '${explicit}' not found. available: ${names}` };
+  }
+  if (workers.length === 0) {
+    return { error: 'no wrangler.jsonc found in cwd' };
+  }
+  if (workers.length === 1) {
+    const [only] = workers;
+    if (!only) return { error: 'no wrangler.jsonc found' };
+    return only;
+  }
+  return {
+    error: `multiple workers found. specify worker: ${workers.map((w) => w.name).join(', ')}`,
+  };
+}
+
+export function readString(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): string | undefined {
+  const v = args?.[key];
+  return typeof v === 'string' ? v : undefined;
+}
+
+export function readBoolean(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): boolean | undefined {
+  const v = args?.[key];
+  return typeof v === 'boolean' ? v : undefined;
+}
+
+export function readStringArray(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): string[] | undefined {
+  const v = args?.[key];
+  if (!Array.isArray(v)) return undefined;
+  const out: string[] = [];
+  for (const item of v) {
+    if (typeof item !== 'string') return undefined;
+    out.push(item);
+  }
+  return out;
+}

package/src/lib/mcp-tools/defs.ts

@@ -0,0 +1,179 @@
+/**
+ * mcp-tools/defs.ts — MCP tool 정의 (JSON Schema literal).
+ *
+ * `commands/mcp.ts` 에서 분리 (2026-06-02 리팩토링) — tool 정의·핸들러를 lib/mcp-tools/ 로
+ * 추출. mcp.ts 는 orchestration (dispatch/buildServer/mcpCmd/__test) 만 유지. 동작 보존.
+ *
+ * 정공법: McpServer high-level 의 zod generic 이 tsc inference OOM (SIGABRT) 유발 →
+ * JSON Schema literal 로 정의, zod 의존성 제거 (mcp.ts 의 low-level Server dispatch 와 정합).
+ */
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations?: { destructiveHint?: boolean; readOnlyHint?: boolean };
+}
+
+export const READ_TOOLS: ToolDef[] = [
+  {
+    name: 'athsra_whoami',
+    description:
+      'Check athsra authentication status for THIS machine. Call this FIRST when onboarding athsra. ' +
+      'Returns { authenticated, userId, machineId } (identity only, NO secrets). If not authenticated, ' +
+      'returns the exact command to run: `athsra login --sso` opens a browser to sign up or log in ' +
+      '(modfolio Connect SSO). All other athsra tools require authentication first.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'athsra_list_projects',
+    description:
+      'List all envelope (project) names accessible to the current athsra user. ' +
+      'Requires prior `athsra login`. Returns string array of project names.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        detail: {
+          type: 'boolean',
+          description: 'If true, return extended rows (versions, last update, etc.).',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'athsra_get_project_keys',
+    description:
+      'Return the list of secret keys stored in a given envelope. ' +
+      'Values are NOT returned for security — only key names. ' +
+      'Use `athsra run <project> -- <cmd>` (outside MCP) to inject values into a process.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1, description: 'Envelope name.' },
+      },
+      required: ['project'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'athsra_show_manifest',
+    description:
+      'Read the secrets manifest (.athsra/secrets.json) for a sibling worker. ' +
+      'The manifest enumerates the keys that opt-in to wrangler secrets sync ' +
+      '(Phase 2.6 default-deny / Option γ). Resolves worker by `cwd` argument; ' +
+      'falls back to process cwd if absent.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: {
+          type: 'string',
+          description: 'Path inside the sibling repo (default: process cwd).',
+        },
+        worker: {
+          type: 'string',
+          description: 'CF worker name if multiple wrangler.jsonc are present.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'athsra_validate_manifest',
+    description:
+      'Compare a sibling worker manifest against the envelope to identify onboarding gaps. ' +
+      'Returns three sets: `allowed` (manifest ∩ envelope — will sync), ' +
+      '`missing` (manifest \\ envelope — onboarding gap, sibling needs `athsra set`), ' +
+      '`excluded` (envelope \\ manifest — intentionally not synced).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        cwd: { type: 'string' },
+        worker: { type: 'string' },
+      },
+      required: ['project'],
+      additionalProperties: false,
+    },
+  },
+];
+
+export const WRITE_TOOLS: ToolDef[] = [
+  {
+    name: 'athsra_set_secret',
+    description:
+      'Add or overwrite a secret key=value in an envelope (E2EE encrypted with master pw). ' +
+      'DESTRUCTIVE — invoke only with explicit user intent. Value is NEVER echoed back. ' +
+      'Use this to onboard new keys identified by athsra_validate_manifest missing list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        key: { type: 'string', minLength: 1, pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+        value: { type: 'string', description: 'Secret value (not logged, not echoed).' },
+      },
+      required: ['project', 'key', 'value'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_unset_secret',
+    description:
+      'Remove a secret key from an envelope. DESTRUCTIVE. Value is irrecoverable unless ' +
+      'a prior version is restored via `athsra rollback`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        key: { type: 'string', minLength: 1 },
+      },
+      required: ['project', 'key'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_manifest_init',
+    description:
+      'Create a new sibling worker manifest (.athsra/secrets.json) with the given keys. ' +
+      'Fails if manifest already exists (use `athsra_manifest_modify` for updates). ' +
+      'Honors host repo biome.json indent style (Phase 2.6.1).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string' },
+        worker: { type: 'string' },
+        keys: {
+          type: 'array',
+          items: { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+          minItems: 1,
+        },
+      },
+      required: ['keys'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_manifest_modify',
+    description: "Add or remove keys from an existing sibling manifest. `op` = 'add' or 'remove'.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        op: { type: 'string', enum: ['add', 'remove'] },
+        cwd: { type: 'string' },
+        worker: { type: 'string' },
+        keys: {
+          type: 'array',
+          items: { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+          minItems: 1,
+        },
+      },
+      required: ['op', 'keys'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+];

package/src/lib/mcp-tools/read.ts

@@ -0,0 +1,156 @@
+/**
+ * mcp-tools/read.ts — read-only MCP tool 핸들러 (항상 노출, secret 값 미노출).
+ *
+ * `commands/mcp.ts` 에서 분리 (2026-06-02 리팩토링). 동작 보존.
+ */
+
+import { inferAdoptContext } from '../adopt-context.ts';
+import { loadAuthContext } from '../auth-context.ts';
+import { readPlain } from '../envelope.ts';
+import { applyManifest, loadManifest } from '../secrets-manifest.ts';
+import { pickWorker, readBoolean, readString } from './args.ts';
+import { isAuthError, jsonError, jsonOk, notLoggedIn, type ToolTextResult } from './result.ts';
+
+/**
+ * athsra_whoami — 현재 머신의 인증 상태 + 신원(userId·machineId·worker URL, 시크릿 X). AI 가 athsra
+ * 온보딩 시 **가장 먼저** 호출해 로그인 필요 여부를 판단한다. 미인증이면 정확한 로그인 명령을 돌려준다
+ * (성공 결과로 — 에러 아님, AI 가 상태를 명확히 읽도록).
+ */
+export async function handleWhoami(): Promise<ToolTextResult> {
+  const ctx = await loadAuthContext();
+  if (!ctx) {
+    return jsonOk({
+      authenticated: false,
+      action:
+        'Run `athsra login --sso` in a terminal — a browser opens to sign up or log in (modfolio Connect SSO).',
+    });
+  }
+  try {
+    const me = await ctx.client.whoami();
+    return jsonOk({
+      authenticated: true,
+      kind: ctx.kind,
+      userId: me.userId,
+      orgId: me.orgId,
+      machineId: me.machineId,
+      label: me.label,
+    });
+  } catch (err) {
+    // 토큰은 있으나 세션 만료(idle timeout)/401 → 미인증으로 보고 + 재로그인 안내.
+    if (isAuthError(err)) {
+      return jsonOk({
+        authenticated: false,
+        reason: 'session expired or idle timeout',
+        action: 'Run `athsra login --sso` to re-authenticate (a browser opens).',
+      });
+    }
+    return jsonError(`whoami failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export async function handleListProjects(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const ctx = await loadAuthContext();
+  if (!ctx) {
+    return notLoggedIn();
+  }
+  const detail = readBoolean(args, 'detail');
+  if (detail) {
+    const rows = await ctx.client.listProjectsExtended();
+    return jsonOk({ projects: rows });
+  }
+  const names = await ctx.client.listProjects();
+  return jsonOk({ projects: names, count: names.length });
+}
+
+export async function handleGetProjectKeys(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  if (!project) return jsonError('missing required arg: project');
+  const ctx = await loadAuthContext();
+  if (!ctx) {
+    return notLoggedIn();
+  }
+  const env = await readPlain(ctx, project);
+  if (!env) {
+    return jsonError(`envelope '${project}' not found`);
+  }
+  const keys = Object.entries(env)
+    .filter(([, v]) => typeof v === 'string' && v.length > 0)
+    .map(([k]) => k)
+    .sort();
+  return jsonOk({ project, keys, count: keys.length });
+}
+
+export function handleShowManifest(args: Record<string, unknown> | undefined): ToolTextResult {
+  const at = readString(args, 'cwd') ?? process.cwd();
+  const worker = readString(args, 'worker');
+  const inferred = inferAdoptContext(at);
+  const picked = pickWorker(inferred.workers, worker);
+  if ('error' in picked) {
+    return jsonError(picked.error);
+  }
+  const loaded = loadManifest({ workerCwd: picked.cwd });
+  if (loaded.error) {
+    return jsonError(`manifest invalid (${loaded.path}): ${loaded.error}`);
+  }
+  if (!loaded.manifest) {
+    return jsonError(
+      `no manifest at ${loaded.path}. create via: athsra manifest init --keys=K1,K2`,
+    );
+  }
+  return jsonOk({
+    worker: picked.name,
+    manifestPath: loaded.path,
+    secrets: loaded.manifest.secrets,
+    count: loaded.manifest.secrets.length,
+  });
+}
+
+export async function handleValidateManifest(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  if (!project) return jsonError('missing required arg: project');
+  const ctx = await loadAuthContext();
+  if (!ctx) {
+    return notLoggedIn();
+  }
+  const at = readString(args, 'cwd') ?? process.cwd();
+  const worker = readString(args, 'worker');
+  const inferred = inferAdoptContext(at);
+  const picked = pickWorker(inferred.workers, worker);
+  if ('error' in picked) {
+    return jsonError(picked.error);
+  }
+  const loaded = loadManifest({ workerCwd: picked.cwd });
+  if (loaded.error) {
+    return jsonError(`manifest invalid (${loaded.path}): ${loaded.error}`);
+  }
+  if (!loaded.manifest) {
+    return jsonError(`no manifest at ${loaded.path}`);
+  }
+  const env = await readPlain(ctx, project);
+  if (!env) {
+    return jsonError(`envelope '${project}' not found`);
+  }
+  const envelopeKeys = Object.entries(env)
+    .filter(([, v]) => typeof v === 'string' && v.length > 0)
+    .map(([k]) => k);
+  const applied = applyManifest(loaded.manifest, envelopeKeys);
+  return jsonOk({
+    worker: picked.name,
+    project,
+    manifestPath: loaded.path,
+    allowed: applied.allowed,
+    missing: applied.missing,
+    excluded: applied.excluded,
+    counts: {
+      allowed: applied.allowed.length,
+      missing: applied.missing.length,
+      excluded: applied.excluded.length,
+    },
+  });
+}

package/src/lib/mcp-tools/result.ts

@@ -0,0 +1,46 @@
+/**
+ * mcp-tools/result.ts — MCP tool 결과 타입 + 헬퍼.
+ *
+ * `commands/mcp.ts` 에서 분리 (2026-06-02 리팩토링). 동작 보존.
+ *
+ * MCP `CallToolResult` 의 subset — content + isError. SDK 의 zod-derived 타입을
+ * 직접 import 하면 tsc inference OOM (SIGABRT) 가 발생하므로 manual 정의.
+ * MCP spec 2025-06-18 의 CallToolResult 와 호환.
+ */
+
+export interface ToolTextResult {
+  content: Array<{ type: 'text'; text: string }>;
+  isError?: boolean;
+  structuredContent?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export function jsonOk(data: unknown): ToolTextResult {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+
+export function jsonError(message: string): ToolTextResult {
+  return { isError: true, content: [{ type: 'text', text: `error: ${message}` }] };
+}
+
+/**
+ * 미인증 시 AI 가 곧바로 행동할 수 있는 안내. `athsra login --sso` 가 브라우저를 열어 modfolio
+ * Connect 로 가입/로그인 → 토큰/master pw 를 OS keyring 에 저장한다. AI-온보딩의 인증 부트스트랩 신호.
+ */
+export function notLoggedIn(): ToolTextResult {
+  return jsonError(
+    'not authenticated on this machine. Run `athsra login --sso` in a terminal — a browser opens ' +
+      'to sign up or log in (modfolio Connect SSO). Then retry this tool. ' +
+      '(headless/CI: set ATHSRA_TOKEN=ats_… service token instead.)',
+  );
+}
+
+/**
+ * 401 / 세션 만료(idle timeout) / unauthorized 류 에러인지. 토큰은 keyring 에 있어도 서버 세션이
+ * 만료되면 호출이 401 → 이 경우도 재로그인 안내(notLoggedIn)로 전환해 AI 가 막히지 않게 한다.
+ */
+export function isAuthError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return /\b401\b|unauthorized|session_idle/i.test(msg);
+}