@athsra/cli 1.0.3 → 1.1.0

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

@@ -12,20 +12,58 @@ export interface ToolDef {
   name: string;
   description: string;
   inputSchema: Record<string, unknown>;
-  annotations?: { destructiveHint?: boolean; readOnlyHint?: boolean };
+  annotations?: {
+    destructiveHint?: boolean;
+    readOnlyHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  };
 }
 
+/**
+ * 환경(config) inputSchema property — secret 도구 공용. optional(required 미포함 = 하위호환).
+ * 핸들러는 `readString(args,'config') ?? 'default'` 로 소비. 값 검증은 worker(sanitizeConfig)가 단일원.
+ */
+const CONFIG_PROP = {
+  config: {
+    type: 'string',
+    description: 'Environment/config (e.g. dev/staging/prod). Optional — defaults to "default".',
+  },
+} as const;
+
 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.',
+      'call athsra_login_start to begin a browser login right from chat (no terminal needed) — ' +
+      'or run `athsra login` in a terminal. All other athsra tools require authentication first.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: { readOnlyHint: true },
   },
+  {
+    name: 'athsra_login_start',
+    description:
+      'Begin a browser-based athsra login from chat — NO terminal needed. Returns a verification ' +
+      'URL, user_code and device key fingerprint to relay to the user. The user opens the URL, ' +
+      'checks the on-screen fingerprint matches (phishing guard), and approves with their master ' +
+      'password — which never leaves the browser. Then poll athsra_login_status. Calling start ' +
+      'while a flow is pending returns the SAME flow (idempotent). The device_code secret never ' +
+      'appears in any response.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: false },
+  },
+  {
+    name: 'athsra_login_status',
+    description:
+      'Poll the pending in-chat login (respect retry_after_seconds — too-fast calls return a ' +
+      'cached status without hitting the server). On approval the identity key + token are ' +
+      'stored in the OS keyring BEFORE this returns status:"approved" — afterwards every athsra ' +
+      'tool works. Terminal states: denied, expired (call athsra_login_start again).',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: false },
+  },
   {
     name: 'athsra_list_projects',
     description:
@@ -52,6 +90,7 @@ export const READ_TOOLS: ToolDef[] = [
       type: 'object',
       properties: {
         project: { type: 'string', minLength: 1, description: 'Envelope name.' },
+        ...CONFIG_PROP,
       },
       required: ['project'],
       additionalProperties: false,
@@ -97,6 +136,57 @@ export const READ_TOOLS: ToolDef[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'athsra_versions',
+    description:
+      'List the version history of a project envelope (version ids, timestamps, sizes) plus a ' +
+      'tombstone if soft-deleted. Metadata only — no secret values. Use to pick a rollback target.',
+    inputSchema: {
+      type: 'object',
+      properties: { project: { type: 'string' }, ...CONFIG_PROP },
+      required: ['project'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'athsra_audit',
+    description:
+      'Query the audit log (who did what, when) — actor/action/path/status metadata, never secret ' +
+      'values. Optional filters: action, actor, cursor (pagination). Returns entries + nextCursor.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string' },
+        actor: { type: 'string' },
+        cursor: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'athsra_list_orgs',
+    description: 'List the orgs you belong to and which one is current (id, slug, role, status).',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'athsra_org_info',
+    description:
+      'Show the current org with its members (identifier, role, status) plus your org list. ' +
+      'Identity/role metadata only — no secrets.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: 'athsra_doctor',
+    description:
+      'Self-diagnose auth/session health when other tools fail (authenticated? session valid?). ' +
+      'Returns checks + a healthy flag. Touches no secrets.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
 ];
 
 export const WRITE_TOOLS: ToolDef[] = [
@@ -112,6 +202,7 @@ export const WRITE_TOOLS: ToolDef[] = [
         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).' },
+        ...CONFIG_PROP,
       },
       required: ['project', 'key', 'value'],
       additionalProperties: false,
@@ -128,6 +219,7 @@ export const WRITE_TOOLS: ToolDef[] = [
       properties: {
         project: { type: 'string', minLength: 1 },
         key: { type: 'string', minLength: 1 },
+        ...CONFIG_PROP,
       },
       required: ['project', 'key'],
       additionalProperties: false,
@@ -176,4 +268,297 @@ export const WRITE_TOOLS: ToolDef[] = [
     },
     annotations: { destructiveHint: true, readOnlyHint: false },
   },
+  {
+    name: 'athsra_rollback',
+    description:
+      'Roll a project envelope back to a previous version (pick from athsra_versions). Requires ' +
+      'confirm=<project>. Creates a new version pointing at the old content.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string' },
+        version: { type: 'string', description: 'version_id from athsra_versions' },
+        confirm: { type: 'string', description: 'must equal the project name to proceed' },
+        ...CONFIG_PROP,
+      },
+      required: ['project', 'version', 'confirm'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_delete_project',
+    description:
+      'Soft-delete a project envelope (recoverable via athsra_restore_project). Requires ' +
+      'confirm=<project>. Hard delete is not exposed over MCP.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string' },
+        confirm: { type: 'string', description: 'must equal the project name to proceed' },
+        ...CONFIG_PROP,
+      },
+      required: ['project', 'confirm'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_restore_project',
+    description:
+      'Restore a soft-deleted project envelope to its last state. Non-destructive — no confirm needed.',
+    inputSchema: {
+      type: 'object',
+      properties: { project: { type: 'string' }, ...CONFIG_PROP },
+      required: ['project'],
+      additionalProperties: false,
+    },
+    annotations: { idempotentHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_bulk_set',
+    description:
+      'Set multiple secrets in one read→merge→write (single version bump). `secrets` is an object ' +
+      'of KEY→value. Values are never echoed back (key names only in the response).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string' },
+        secrets: { type: 'object', additionalProperties: { type: 'string' } },
+        ...CONFIG_PROP,
+      },
+      required: ['project', 'secrets'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+];
+
+/**
+ * value tier (1.2.0) — secret 평문이 응답 경계를 넘는 도구 (get_secret_value/run).
+ * `ATHSRA_MCP_READ_VALUES=1` opt-in 시에만 노출·dispatch. write(변경)·admin(계정수술)과
+ * 위험 축이 직교 — "값 읽기"만 별도 게이트. get_secret_value 는 기본 마스킹(prefix+length+
+ * sha256), full 평문은 opt-in + confirm=<project> 이중 게이트. run 은 값 미노출 주입 실행.
+ * athsra MCP 는 outward 도구가 없어 단독 trifecta 미형성 — 값을 본 호출측 agent 의 외부
+ * 전송은 그 agent 의 disallowedTools 책임 (description 경고 + governance private-pattern).
+ */
+export const VALUE_TOOLS: ToolDef[] = [
+  {
+    name: 'athsra_get_secret_value',
+    description:
+      'Reveal a secret value from an envelope. SAFE-BY-DEFAULT: returns a MASKED descriptor ' +
+      '(value prefix + length + sha256) unless full=true. full=true requires BOTH ' +
+      'ATHSRA_MCP_READ_VALUES=1 (server env) AND confirm=<project>. NOTE: athsra has no ' +
+      'outward/send tools — but the CALLING agent might. Never paste a revealed value into ' +
+      'another tool (Slack/Gmail/email/web). Prefer athsra_run to inject values into a process ' +
+      'WITHOUT seeing them.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1, description: 'Envelope name.' },
+        key: { type: 'string', minLength: 1, description: 'Secret key to reveal.' },
+        full: {
+          type: 'boolean',
+          description:
+            'Reveal full plaintext (requires ATHSRA_MCP_READ_VALUES=1 + confirm). Default false = masked.',
+        },
+        confirm: { type: 'string', description: 'Must equal project name when full=true.' },
+        ...CONFIG_PROP,
+      },
+      required: ['project', 'key'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false },
+  },
+  {
+    name: 'athsra_run',
+    description:
+      'Run a command with the envelope secrets injected as env vars — WITHOUT exposing values to ' +
+      'you. Returns exit code (and, only if return_output=true, captured output scrubbed of known ' +
+      'secret values). Known build/runtime commands (bun/node/npm/pnpm/yarn/wrangler/bunx/npx/' +
+      'vite/tsx) run directly; any other command requires confirm=<project> (deliberate-exec ' +
+      'gate). Mirrors `athsra run <project> -- <cmd>`. Secret values never appear in the response.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1, description: 'Envelope name.' },
+        command: {
+          type: 'string',
+          minLength: 1,
+          description: 'Executable (e.g. "bun", "wrangler").',
+        },
+        args: { type: 'array', items: { type: 'string' }, description: 'Command arguments.' },
+        cwd: { type: 'string', description: 'Working directory (default: process cwd).' },
+        return_output: {
+          type: 'boolean',
+          description: 'Include scrubbed stdout/stderr in the response (default false).',
+        },
+        timeout_ms: {
+          type: 'integer',
+          minimum: 1000,
+          maximum: 600000,
+          description: 'Kill the child after N ms (default 120000).',
+        },
+        confirm: {
+          type: 'string',
+          description: 'Must equal project for non-allowlisted commands.',
+        },
+        ...CONFIG_PROP,
+      },
+      required: ['project', 'command'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  },
+];
+
+/**
+ * admin tier (Phase 5 B1 골격 → B4 +7) — org/멤버/service-token/purge 고위험 도구.
+ * `ATHSRA_MCP_ADMIN=1` opt-in 시에만 노출·dispatch. destructive 는 confirm 정확일치
+ * (requireConfirm, auth 전 차단). master pw 소비 3종(remove_member/share/token_create)은
+ * identity 디바이스에서 actionable 거부. 시크릿 값 무노출 — 유일 예외 service_token_create
+ * 의 1회성 ats_* (warning 동반).
+ */
+export const ADMIN_TOOLS: ToolDef[] = [
+  {
+    name: 'athsra_org_invite',
+    description:
+      'Invite a member to the current org by identifier (email). Unknown identifiers create a ' +
+      'JIT pending user. role: member (default) or admin. The invitee accepts via `athsra login` ' +
+      'then `athsra org use`. Envelope access is separate — share per project with ' +
+      'athsra_project_share afterwards.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: {
+          type: 'string',
+          minLength: 1,
+          description: 'Member email (or numeric user id).',
+        },
+        role: { type: 'string', enum: ['member', 'admin'] },
+      },
+      required: ['identifier'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false },
+  },
+  {
+    name: 'athsra_org_remove_member',
+    description:
+      'Remove a member from the current org (their org tokens are revoked). Requires ' +
+      'confirm=<identifier> (exact match — deliberate-action gate). When called by the org ' +
+      'owner, DEKs of envelopes shared with the removed member are rotated (real cryptographic ' +
+      'revocation); non-owner callers get a follow-up instruction instead. Consumes the master ' +
+      'password — not available on identity-mode devices.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        identifier: {
+          type: 'string',
+          minLength: 1,
+          description: 'Member email or user id (athsra_org_info).',
+        },
+        confirm: { type: 'string', description: 'must equal identifier to proceed' },
+      },
+      required: ['identifier', 'confirm'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_project_share',
+    description:
+      'Share ONE project with an org member: grants the worker ACL (read or write) and re-wraps ' +
+      'the envelope DEK to the member public key (E2EE member recipient — the server never sees ' +
+      'plaintext). The member must have provisioned an identity key via `athsra login` first. ' +
+      'Consumes the master password — not available on identity-mode devices.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        identifier: { type: 'string', minLength: 1, description: 'Member email or user id.' },
+        perms: { type: 'string', enum: ['read', 'write'], description: 'default read' },
+      },
+      required: ['project', 'identifier'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false },
+  },
+  {
+    name: 'athsra_project_unshare',
+    description:
+      "Revoke a member's ACL on one project — API access is blocked immediately. HONEST " +
+      'LIMITATION: the envelope DEK and member recipient are NOT rotated, so a member who ' +
+      'already cached the envelope can still decrypt past versions. For cryptographic ' +
+      'revocation the owner removes the member (athsra_org_remove_member), which rotates DEKs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        identifier: { type: 'string', minLength: 1, description: 'Member email or user id.' },
+      },
+      required: ['project', 'identifier'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_service_token_create',
+    description:
+      'Create a scoped service token (ats_*) for one project — headless hosts / CI decrypt the ' +
+      'envelope E2EE without the master password. expires_days is REQUIRED (1..365): ' +
+      'MCP-issued credentials always expire. THE ONLY athsra tool that returns a credential — ' +
+      'the token is shown exactly once; store it immediately in a secret store, never in code ' +
+      'or chat. Consumes the master password — not available on identity-mode devices.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        label: {
+          type: 'string',
+          minLength: 1,
+          description: 'Identifier for audit/rotation (e.g. "nas-docker").',
+        },
+        perms: { type: 'string', enum: ['read', 'write'], description: 'default read' },
+        expires_days: { type: 'integer', minimum: 1, maximum: 365 },
+      },
+      required: ['project', 'label', 'expires_days'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false },
+  },
+  {
+    name: 'athsra_service_token_revoke',
+    description:
+      'Revoke a service token (ats_*) immediately — worker auth rejects it at once (D1 strong ' +
+      'consistency). Use on leak suspicion or rotation. The stale envelope recipient entry left ' +
+      'behind is harmless (auth-by-hash already refuses).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        token: { type: 'string', minLength: 1, description: 'The ats_… token to revoke.' },
+      },
+      required: ['token'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
+  {
+    name: 'athsra_purge',
+    description:
+      'PERMANENTLY hard-delete a project: every version, the current pointer and any tombstone ' +
+      'are removed — NOT recoverable, unlike athsra_delete_project (soft). Requires ' +
+      'confirm=<project> (exact match).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', minLength: 1 },
+        confirm: { type: 'string', description: 'must equal the project name to proceed' },
+        ...CONFIG_PROP,
+      },
+      required: ['project', 'confirm'],
+      additionalProperties: false,
+    },
+    annotations: { destructiveHint: true, readOnlyHint: false },
+  },
 ];

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

@@ -0,0 +1,156 @@
+/**
+ * mcp-tools/login.ts — Phase 5 B5. MCP in-chat 로그인 (athsra_login_start / athsra_login_status).
+ *
+ * AI 가 터미널 없이 채팅 안에서 인증을 부트스트랩한다:
+ *   start → user 에게 URL+user_code+fingerprint 전달 → 브라우저 승인(master pw 는 거기서만)
+ *   → status poll → approved 시 keyring 저장 완료 후 반환 → 이후 전 도구 사용 가능.
+ *
+ * 보안:
+ *   - device_code 는 모듈 메모리(activeFlow)에만 — 어떤 응답에도 미포함 (탈취=토큰 가로채기).
+ *   - 단일 activeFlow — start 재호출은 진행 중 flow 를 재반환 (device code 남발 방지).
+ *   - RFC 8628 interval 준수 — 과속 status 호출은 worker 미타격, 캐시 + retry_after 반환.
+ */
+
+import {
+  completeIdentityLogin,
+  type IdentityFlow,
+  pollDeviceTokenOnce,
+  startIdentityFlow,
+} from '../device-login.ts';
+import { jsonError, jsonOk, type ToolTextResult } from './result.ts';
+
+interface ActiveFlow {
+  flow: IdentityFlow;
+  /** 마지막 worker poll 시각 (epoch ms) — interval 준수 게이트. start 시각으로 초기화. */
+  lastPollAt: number;
+  /** slow_down 반영된 현재 interval. */
+  intervalMs: number;
+}
+
+let activeFlow: ActiveFlow | null = null;
+
+function pendingPayload(flow: IdentityFlow, intervalMs: number): Record<string, unknown> {
+  return {
+    status: 'pending',
+    verification_uri_complete: flow.verificationUriComplete,
+    user_code: flow.userCode,
+    device_key_fingerprint: flow.fingerprint,
+    expires_in_seconds: Math.max(0, Math.round((flow.expiresAt - Date.now()) / 1000)),
+    retry_after_seconds: Math.ceil(intervalMs / 1000),
+    instructions:
+      'Show the user this URL and code. They open it in a browser, sign in (or sign up), verify ' +
+      'the fingerprint shown on screen matches device_key_fingerprint above (phishing guard), ' +
+      'and approve with their master password — it never leaves the browser. ' +
+      'Then call athsra_login_status (respect retry_after_seconds).',
+  };
+}
+
+/** athsra_login_start — 브라우저 승인 flow 시작. 진행 중이면 같은 flow 재반환 (멱등). */
+export async function handleLoginStart(): Promise<ToolTextResult> {
+  if (activeFlow && Date.now() < activeFlow.flow.expiresAt) {
+    return jsonOk({
+      ...pendingPayload(activeFlow.flow, activeFlow.intervalMs),
+      note: 'a login flow is already in progress — showing the SAME pending flow (no new code minted).',
+    });
+  }
+  let flow: IdentityFlow;
+  try {
+    flow = await startIdentityFlow();
+  } catch (err) {
+    return jsonError(err instanceof Error ? err.message : String(err));
+  }
+  activeFlow = { flow, lastPollAt: Date.now(), intervalMs: flow.intervalMs };
+  return jsonOk(pendingPayload(flow, flow.intervalMs));
+}
+
+/** athsra_login_status — poll 1회 (interval 준수). approved 는 keyring 저장 완료 후 반환. */
+export async function handleLoginStatus(): Promise<ToolTextResult> {
+  if (!activeFlow) {
+    return jsonError('no login flow in progress — call athsra_login_start first.');
+  }
+  const { flow } = activeFlow;
+  if (Date.now() >= flow.expiresAt) {
+    activeFlow = null;
+    return jsonOk({
+      status: 'expired',
+      hint: 'the approval window passed — call athsra_login_start to begin a new flow.',
+    });
+  }
+  // interval 준수 — 과속이면 worker 미타격, 캐시된 pending + retry_after 반환 (RFC 8628).
+  const sinceLastPoll = Date.now() - activeFlow.lastPollAt;
+  if (sinceLastPoll < activeFlow.intervalMs) {
+    return jsonOk({
+      ...pendingPayload(flow, activeFlow.intervalMs),
+      retry_after_seconds: Math.ceil((activeFlow.intervalMs - sinceLastPoll) / 1000),
+      note: 'polled too fast — cached status returned without hitting the server.',
+    });
+  }
+  activeFlow.lastPollAt = Date.now();
+  const step = await pollDeviceTokenOnce(flow.client, flow.deviceCode);
+  switch (step.step) {
+    case 'pending':
+    case 'network':
+      return jsonOk(pendingPayload(flow, activeFlow.intervalMs));
+    case 'slow_down':
+      activeFlow.intervalMs += 5000;
+      return jsonOk({
+        ...pendingPayload(flow, activeFlow.intervalMs),
+        note: 'server asked to slow down — interval increased.',
+      });
+    case 'denied':
+      activeFlow = null;
+      return jsonOk({
+        status: 'denied',
+        hint: 'the user rejected the approval. Call athsra_login_start to retry if intended.',
+      });
+    case 'expired':
+      activeFlow = null;
+      return jsonOk({
+        status: 'expired',
+        hint: 'the approval window passed — call athsra_login_start to begin a new flow.',
+      });
+    case 'token': {
+      const result = step.result;
+      if (result.tokenType !== 'user') {
+        activeFlow = null;
+        return jsonError('unexpected service token for identity login — start over.');
+      }
+      try {
+        const { userId } = await completeIdentityLogin({
+          result,
+          devicePrivateKey: flow.devicePrivateKey,
+          machineId: flow.machineId,
+          workerUrl: flow.workerUrl,
+          existingCreatedAt: flow.existingCreatedAt,
+        });
+        activeFlow = null;
+        return jsonOk({
+          status: 'approved',
+          user_id: userId,
+          machine_id: flow.machineId,
+          note:
+            'identity key + token stored in the OS keyring — all athsra tools now work on this ' +
+            'machine. The master password was never on this device.',
+        });
+      } catch (err) {
+        activeFlow = null;
+        return jsonError(
+          `identity key unseal failed: ${err instanceof Error ? err.message : String(err)} — call athsra_login_start to retry.`,
+        );
+      }
+    }
+  }
+}
+
+/** test helpers — activeFlow 조작 (interval 게이트/상태 전이 검증용). */
+export const __test = {
+  reset(): void {
+    activeFlow = null;
+  },
+  get(): ActiveFlow | null {
+    return activeFlow;
+  },
+  rewindLastPoll(): void {
+    if (activeFlow) activeFlow.lastPollAt = 0;
+  },
+};

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

@@ -0,0 +1,41 @@
+/**
+ * mcp-tools/mask.ts — secret 값 마스킹 + 출력 scrub (value tier 안전 노출).
+ *
+ * value tier(ATHSRA_MCP_READ_VALUES) 도구가 평문을 다룰 때, 기본은 마스킹된
+ * descriptor 만 노출(존재/형태/무결성 확인 가능, 역산 불가). full 평문은 명시
+ * 게이트(opt-in + confirm) 통과 시에만. athsra_run 의 캡처 출력은 secret 값을
+ * 제거(scrub)해 자식이 echo 한 secret 이 응답으로 새지 않게 한다.
+ */
+import { createHash } from 'node:crypto';
+
+export interface MaskedSecret {
+  masked: true;
+  key: string;
+  /** 앞 4자 (값 길이 8+ 일 때만 — 짧은 값 전체 추측 방지). 짧으면 ''. */
+  prefix: string;
+  length: number;
+  /** 전체 평문의 sha256 hex (값 비교·무결성 확인용, 역산 불가). */
+  sha256: string;
+}
+
+/** 값을 노출하지 않는 descriptor — 존재/형태/무결성 확인용. */
+export function maskValue(key: string, value: string): MaskedSecret {
+  const sha256 = createHash('sha256').update(value, 'utf8').digest('hex');
+  const prefix = value.length >= 8 ? value.slice(0, 4) : '';
+  return { masked: true, key, prefix, length: value.length, sha256 };
+}
+
+/**
+ * 텍스트에서 알려진 secret 값을 ***REDACTED*** 로 치환한다. 8자 이상 값만(짧은
+ * 값은 오탐 위험). 긴 값부터 치환해 부분 매칭(짧은 값이 긴 값의 부분)을 피한다.
+ */
+export function scrubSecrets(text: string, plain: Record<string, string>): string {
+  const values = Object.values(plain)
+    .filter((v) => v.length >= 8)
+    .sort((a, b) => b.length - a.length);
+  let out = text;
+  for (const value of values) {
+    out = out.split(value).join('***REDACTED***');
+  }
+  return out;
+}