@athsra/cli 1.0.4 → 1.1.1

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

@@ -0,0 +1,267 @@
+/**
+ * mcp-tools/admin.ts — Phase 5 B4. admin tier 핸들러 (`ATHSRA_MCP_ADMIN=1` opt-in 시에만 dispatch).
+ *
+ * 7 도구: org_invite / org_remove_member / project_share / project_unshare /
+ * service_token_create / service_token_revoke / purge.
+ *
+ * 핸들러 순서 (write.ts 패턴): args 검증 → requireConfirm(destructive, auth 로드 **전** 조기 차단)
+ * → loadAuthContext → kind 가드 → client 호출 → jsonOk.
+ *
+ * kind 가드 2단 (epic D-2):
+ *   - **master pw 소비 3종** (org_remove_member 의 owner DEK 회전 / project_share 의 envelope
+ *     재포장 / service_token_create 의 recipient wrap) 은 user(master pw) 전용 — identity
+ *     디바이스에선 masterPwDenied 로 actionable 거부 (master pw 는 그 머신에 영원히 없음).
+ *   - 나머지 4종은 user|identity (둘 다 user-급 토큰) — service token 은 7종 전부 거부.
+ *
+ * 시크릿 값 무노출 (epic D-1) — 유일 예외는 service_token_create 의 1회성 ats_* 반환
+ * (ONE-TIME EXPOSURE warning 동반). 그 외 응답은 메타데이터만.
+ */
+
+import { loadAuthContext } from '../auth-context.ts';
+import type { AthsraClient } from '../client.ts';
+import { grantOrgAccess, rotateAfterRemoval } from '../org-rewrap.ts';
+import { createServiceTokenWithRecipient } from '../service-tokens.ts';
+import { readInteger, readString } from './args.ts';
+import { requireConfirm } from './confirm.ts';
+import { jsonError, jsonOk, notLoggedIn, type ToolTextResult } from './result.ts';
+
+/**
+ * master pw 소비 도구의 비-user ctx 거부 메시지. identity 디바이스는 설계상 master pw 가 절대
+ * 없으므로(D-2) "어디서 실행해야 하는지" 를 안내 — AI 가 다음 행동을 고를 수 있게.
+ */
+export function masterPwDenied(tool: string, kind: 'identity' | 'service'): ToolTextResult {
+  if (kind === 'identity') {
+    return jsonError(
+      `${tool} consumes the master password (envelope DEK re-wrap), which never exists on this ` +
+        'identity-mode device by design. Run it on a master-pw machine (`athsra login --password`) ' +
+        'or use the dashboard — the browser is where the master password lives.',
+    );
+  }
+  return jsonError(
+    `${tool} requires a user-level token — scoped service tokens cannot perform admin operations.`,
+  );
+}
+
+/** identifier(이메일 등) 또는 숫자 문자열 → 현재 org 멤버 user_id (org.ts grantAccessCmd 미러). */
+async function resolveMemberUserId(
+  client: AthsraClient,
+  identifier: string,
+): Promise<number | { error: string }> {
+  const direct = Number(identifier);
+  if (Number.isInteger(direct) && direct > 0) return direct;
+  const { members } = await client.listOrgMembers();
+  const member = members.find((m) => m.identifier === identifier);
+  if (!member) {
+    return {
+      error: `'${identifier}' is not a member of the current org — use athsra_org_info to list members`,
+    };
+  }
+  return member.user_id;
+}
+
+/** 현재 org 에서의 내 role (org.ts currentOrgRole 미러 — commands→lib 역참조 회피용 재구현). */
+async function currentOrgRole(client: AthsraClient): Promise<'owner' | 'admin' | 'member' | null> {
+  const { orgs } = await client.listOrgs();
+  return orgs.find((o) => o.is_current)?.role ?? null;
+}
+
+/** athsra_org_invite — 현재 org 에 멤버 초대 (JIT pending user 생성 가능). 토큰-레벨 op. */
+export async function handleOrgInvite(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const identifier = readString(args, 'identifier');
+  if (!identifier) return jsonError('missing required arg: identifier (email)');
+  const role = readString(args, 'role') ?? 'member';
+  if (role !== 'member' && role !== 'admin') {
+    return jsonError("invalid 'role' — must be 'member' or 'admin'");
+  }
+  const ctx = await loadAuthContext();
+  if (!ctx) return notLoggedIn();
+  if (ctx.kind === 'service') return masterPwDenied('org_invite', 'service');
+  const res = await ctx.client.inviteMember({ identifier, role });
+  return jsonOk({
+    ...res,
+    next:
+      'invitee: `athsra login` then `athsra org use <slug>` to accept. Envelope access is ' +
+      'separate — share per project with athsra_project_share, or all projects via CLI ' +
+      '`athsra org grant-access`.',
+  });
+}
+
+/**
+ * athsra_org_remove_member — 멤버 제거 + (owner 호출 시) DEK 회전 스윕 (real revocation).
+ * confirm=<identifier> 정확일치. master pw 소비 (owner 회전 경로) — identity 거부.
+ */
+export async function handleOrgRemoveMember(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const identifier = readString(args, 'identifier');
+  if (!identifier) {
+    return jsonError(
+      'missing required arg: identifier (member email or user id — athsra_org_info)',
+    );
+  }
+  const denied = requireConfirm(args, identifier);
+  if (denied) return denied;
+  const ctx = await loadAuthContext();
+  if (!ctx) return notLoggedIn();
+  if (ctx.kind !== 'user') return masterPwDenied('org_remove_member', ctx.kind);
+  const resolved = await resolveMemberUserId(ctx.client, identifier);
+  if (typeof resolved !== 'number') return jsonError(resolved.error);
+  const res = await ctx.client.removeMember(resolved);
+  // owner 면 DEK 회전 (org.ts removeCmd 미러) — 제거 멤버의 캐시 DEK 무효화.
+  const role = await currentOrgRole(ctx.client);
+  if (role === 'owner') {
+    const rot = await rotateAfterRemoval(ctx.client, ctx.masterPw, resolved);
+    return jsonOk({ ...res, dek_rotation: rot });
+  }
+  return jsonOk({
+    ...res,
+    dek_rotation:
+      'skipped — only the org owner can rotate DEKs (master re-wrap). Have the owner run ' +
+      `\`athsra org rotate-after-removal ${resolved}\` for cryptographic revocation.`,
+  });
+}
+
+/**
+ * athsra_project_share — 단일 project 를 멤버에 공유: worker ACL(read|write) + envelope 멤버
+ * recipient 재포장 (grantOrgAccess projects 필터). master pw 소비 — identity 거부.
+ */
+export async function handleProjectShare(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  const identifier = readString(args, 'identifier');
+  if (!project || !identifier) return jsonError('missing required args: project, identifier');
+  const perms = readString(args, 'perms') ?? 'read';
+  if (perms !== 'read' && perms !== 'write') {
+    return jsonError("invalid 'perms' — must be 'read' or 'write'");
+  }
+  const ctx = await loadAuthContext();
+  if (!ctx) return notLoggedIn();
+  if (ctx.kind !== 'user') return masterPwDenied('project_share', ctx.kind);
+  const resolved = await resolveMemberUserId(ctx.client, identifier);
+  if (typeof resolved !== 'number') return jsonError(resolved.error);
+  await ctx.client.grantAcl({ project, userId: resolved, perms });
+  const rewrap = await grantOrgAccess(ctx.client, ctx.masterPw, resolved, {
+    projects: [project],
+  });
+  return jsonOk({
+    project,
+    user_id: resolved,
+    perms,
+    acl: 'granted',
+    rewrap,
+    ...(rewrap.legacyV1.length > 0
+      ? {
+          note: 'v1 envelope cannot take member recipients — run `athsra migrate-envelopes` first, then re-share.',
+        }
+      : {}),
+  });
+}
+
+/**
+ * athsra_project_unshare — 멤버 ACL 철회 (API 접근 즉시 차단). 한계 정직 명시: DEK/recipient
+ * 미회전 — 캐시 보유 멤버는 과거 버전 복호 가능. 암호학적 철회는 org_remove_member(owner).
+ */
+export async function handleProjectUnshare(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  const identifier = readString(args, 'identifier');
+  if (!project || !identifier) return jsonError('missing required args: project, identifier');
+  const ctx = await loadAuthContext();
+  if (!ctx) return notLoggedIn();
+  if (ctx.kind === 'service') return masterPwDenied('project_unshare', 'service');
+  const resolved = await resolveMemberUserId(ctx.client, identifier);
+  if (typeof resolved !== 'number') return jsonError(resolved.error);
+  await ctx.client.revokeAcl({ project, userId: resolved });
+  return jsonOk({
+    project,
+    user_id: resolved,
+    acl: 'revoked',
+    limitation:
+      'API access is blocked immediately, but the envelope DEK and member recipient are NOT ' +
+      'rotated — a member who already cached the envelope can still decrypt past versions. ' +
+      'For cryptographic revocation, the owner removes the member from the org ' +
+      '(athsra_org_remove_member), which rotates DEKs.',
+  });
+}
+
+/**
+ * athsra_service_token_create — scoped service token 발급 + envelope recipient 추가.
+ * expires_days 필수 1..365 (MCP 발급 자격증명은 반드시 만료). 유일한 자격증명-반환 도구.
+ * master pw 소비 — identity 거부.
+ */
+export async function handleServiceTokenCreate(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  const label = readString(args, 'label');
+  if (!project || !label) return jsonError('missing required args: project, label');
+  const perms = readString(args, 'perms') ?? 'read';
+  if (perms !== 'read' && perms !== 'write') {
+    return jsonError("invalid 'perms' — must be 'read' or 'write'");
+  }
+  const expiresDays = readInteger(args, 'expires_days');
+  if (expiresDays === undefined || expiresDays < 1 || expiresDays > 365) {
+    return jsonError(
+      'expires_days is required and must be an integer 1..365 — MCP-issued credentials always expire.',
+    );
+  }
+  const ctx = await loadAuthContext();
+  if (!ctx) return notLoggedIn();
+  if (ctx.kind !== 'user') return masterPwDenied('service_token_create', ctx.kind);
+  const created = await createServiceTokenWithRecipient(ctx, {
+    project,
+    label,
+    perms,
+    expiresInDays: expiresDays,
+  });
+  return jsonOk({
+    ...created,
+    warning:
+      'ONE-TIME EXPOSURE — this is the only athsra tool that returns a credential, and the ' +
+      'token is shown exactly once. Store it NOW (password manager / CI secret store), never ' +
+      'in code or chat logs. Headless usage: ATHSRA_TOKEN=ats_… athsra run -- <cmd>.',
+  });
+}
+
+/** athsra_service_token_revoke — ats_* 즉시 무효화 (D1 strong consistency). 토큰-레벨 op. */
+export async function handleServiceTokenRevoke(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const token = readString(args, 'token');
+  if (!token) return jsonError('missing required arg: token (ats_…)');
+  if (!token.startsWith('ats_')) return jsonError('service token must start with ats_');
+  const ctx = await loadAuthContext();
+  if (!ctx) return notLoggedIn();
+  if (ctx.kind === 'service') return masterPwDenied('service_token_revoke', 'service');
+  const res = await ctx.client.revoke(token);
+  return jsonOk({
+    ok: res.ok,
+    revoked: res.revoked,
+    note: 'worker auth rejects the token immediately; the stale envelope recipient entry left behind is harmless.',
+  });
+}
+
+/** athsra_purge — hard delete (모든 versions+tombstone 영구 제거, 복구 불가). confirm=project. */
+export async function handlePurge(
+  args: Record<string, unknown> | undefined,
+): Promise<ToolTextResult> {
+  const project = readString(args, 'project');
+  if (!project) return jsonError('missing required arg: project');
+  const config = readString(args, 'config') ?? 'default';
+  const denied = requireConfirm(args, project);
+  if (denied) return denied;
+  const ctx = await loadAuthContext();
+  if (!ctx) return notLoggedIn();
+  if (ctx.kind === 'service') return masterPwDenied('purge', 'service');
+  const res = await ctx.client.deleteProject(project, { hard: true, config });
+  return jsonOk({
+    project,
+    action: 'purged',
+    removed_versions: res.removed_versions ?? 0,
+    warning: 'all version history permanently removed — NOT recoverable',
+  });
+}

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

@@ -37,6 +37,15 @@ export function readString(
   return typeof v === 'string' ? v : undefined;
 }
 
+/** args[key] 가 정수면 반환 (expires_days 등). 소수·문자열·NaN 은 undefined. */
+export function readInteger(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): number | undefined {
+  const v = args?.[key];
+  return typeof v === 'number' && Number.isInteger(v) ? v : undefined;
+}
+
 export function readBoolean(
   args: Record<string, unknown> | undefined,
   key: string,
@@ -58,3 +67,20 @@ export function readStringArray(
   }
   return out;
 }
+
+/**
+ * args[key] 가 string→string 레코드면 반환 (bulk_set 등). 값 중 하나라도 non-string 이면 undefined.
+ */
+export function readRecordOfStrings(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): Record<string, string> | undefined {
+  const v = args?.[key];
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) return undefined;
+  const out: Record<string, string> = {};
+  for (const [k, val] of Object.entries(v)) {
+    if (typeof val !== 'string') return undefined;
+    out[k] = val;
+  }
+  return out;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * mcp-tools/confirm.ts — Phase 5 B1. destructive admin tool 의 confirm 파라미터 검증.
+ *
+ * auth 로드(네트워크·keyring) 전에 호출 — 잘못된/누락된 confirm 을 조기 차단(불필요한 인증 회피
+ * + 실수 방지). args.confirm 이 expected(project·identifier 등 호출자가 명시해야 하는 값)와
+ * 정확히 일치해야 null(통과) 반환, 아니면 actionable error result.
+ */
+import { jsonError, type ToolTextResult } from './result.ts';
+
+export function requireConfirm(
+  args: Record<string, unknown> | undefined,
+  expected: string,
+): ToolTextResult | null {
+  const confirm = args?.confirm;
+  if (typeof confirm !== 'string' || confirm !== expected) {
+    return jsonError(
+      `confirmation required — pass confirm="${expected}" to proceed (irreversible/high-impact action).`,
+    );
+  }
+  return null;
+}