@athsra/cli 1.0.2 → 1.0.3

package/src/commands/org.ts

@@ -0,0 +1,363 @@
+/**
+ * org.ts — Phase 4 Slice 6a org 멀티테넌시 CLI (Slack/GitHub-org 식 "현재 org" 모델).
+ *
+ *   athsra org create <name>                     — company org 생성 (생성자 = owner)
+ *   athsra org ls                                — 내가 멤버인 org 목록 (* = 현재)
+ *   athsra org members                           — 현재 org 멤버
+ *   athsra org invite <identifier> [--role=R]    — 현재 org 에 멤버 초대 (member|admin, JIT pending)
+ *   athsra org remove <user_id>                  — 현재 org 에서 멤버 제거
+ *   athsra org use <slug|id>                     — org 컨텍스트 전환 (token re-mint + config 기록)
+ *   athsra org leave                             — 현재 org 탈퇴
+ *
+ * 관리(invite/remove)는 그 org 의 owner/admin role. switch 후 그 org 컨텍스트에서 동작한다.
+ */
+
+import { loadAuthContext, type UserAuthContext } from '../lib/auth-context.ts';
+import { saveConfig } from '../lib/config.ts';
+import { setToken } from '../lib/keyring.ts';
+import { grantOrgAccess, type RevokeRotateResult, rotateAfterRemoval } from '../lib/org-rewrap.ts';
+
+const USAGE = [
+  'usage:',
+  '  athsra org create <name>                   — company org 생성 (owner)',
+  '  athsra org ls                              — 내가 멤버인 org 목록 (* = 현재)',
+  '  athsra org members                         — 현재 org 멤버',
+  '  athsra org invite <identifier> [--role=member|admin]  — 멤버 초대 (JIT pending)',
+  '  athsra org remove <user_id>                — 멤버 제거 (owner 면 DEK 자동 회전)',
+  '  athsra org rotate-after-removal <user_id>  — 제거 후 DEK 회전 재개 (부분 실패 복구, owner)',
+  '  athsra org grant-access <identifier|id> [--replace]  — 멤버에게 공유 시크릿 re-wrap (--replace=key reset 복구)',
+  '  athsra org use <slug|id>                   — org 컨텍스트 전환',
+  '  athsra org leave                           — 현재 org 탈퇴',
+].join('\n');
+
+async function userCtx(): Promise<UserAuthContext | null> {
+  const ctx = await loadAuthContext();
+  if (!ctx) return null;
+  if (ctx.kind !== 'user') {
+    console.error('org 명령은 user token (master pw) 가 필요합니다. service token 거부.');
+    return null;
+  }
+  return ctx;
+}
+
+/** 현재 org 에서 caller 의 role (DEK 회전은 owner 만 — master 재wrap 필요). */
+async function currentOrgRole(ctx: UserAuthContext): Promise<'owner' | 'admin' | 'member' | null> {
+  const { orgs } = await ctx.client.listOrgs();
+  return orgs.find((o) => o.is_current)?.role ?? null;
+}
+
+/** DEK 회전 스윕 결과 출력 (removeCmd 자동 회전 + rotate-after-removal 복구 공용). */
+function reportRotation(res: RevokeRotateResult): void {
+  const parts = [`rotated ${res.rotated.length}`, `skipped ${res.skipped.length}`];
+  if (res.legacyV1.length) parts.push(`v1 ${res.legacyV1.length}`);
+  if (res.failed.length) parts.push(`failed ${res.failed.length}`);
+  console.log(`  DEK 회전 — ${parts.join(' · ')}`);
+  if (res.rotated.length) {
+    console.log(`  회전: ${res.rotated.join(', ')}`);
+    console.log(
+      '  ⓘ 제거 멤버가 이미 본 평문 값은 무효화되지 않습니다 — 민감 시크릿은 값 자체를 별도 로테이션 권고.',
+    );
+  }
+  for (const r of res.reissue) {
+    console.log(
+      `  ⚠ ${r.project}: service token 재발급 필요 (${r.serviceIds.join(', ')}) — DEK 회전으로 무효화됨`,
+    );
+  }
+  if (res.legacyV1.length) {
+    console.log(`  v1 envelope(회전 불가 — recipient 모델 없음): ${res.legacyV1.join(', ')}`);
+  }
+  for (const f of res.failed) console.error(`  ✗ ${f.project}: ${f.error}`);
+}
+
+async function createOrgCmd(args: string[]): Promise<number> {
+  const name = args
+    .filter((a) => !a.startsWith('-'))
+    .join(' ')
+    .trim();
+  if (!name) {
+    console.error('usage: athsra org create <name>');
+    return 2;
+  }
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  try {
+    const res = await ctx.client.createOrg(name);
+    console.log(`✓ org created: #${res.id} ${res.slug} (${res.type}) — 너는 owner`);
+    console.log(`  전환: athsra org use ${res.slug}`);
+    return 0;
+  } catch (err) {
+    console.error(`✗ create failed: ${(err as Error).message}`);
+    return 1;
+  }
+}
+
+async function lsOrgsCmd(): Promise<number> {
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  const { orgs } = await ctx.client.listOrgs();
+  if (orgs.length === 0) {
+    console.log('(no orgs)');
+    return 0;
+  }
+  for (const o of orgs) {
+    const cur = o.is_current ? '*' : ' ';
+    const pend = o.status === 'pending' ? '  (pending invite — `org use` 로 수락)' : '';
+    console.log(`${cur} ${o.slug}  [${o.role}]  #${o.id}${pend}`);
+  }
+  return 0;
+}
+
+async function membersCmd(): Promise<number> {
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  try {
+    const { members } = await ctx.client.listOrgMembers();
+    if (members.length === 0) {
+      console.log('(no members)');
+      return 0;
+    }
+    for (const m of members) {
+      const pend = m.status === 'pending' ? '  (pending)' : '';
+      console.log(`  #${m.user_id} ${m.identifier}  [${m.role}]${pend}`);
+    }
+    return 0;
+  } catch (err) {
+    console.error(`✗ members failed: ${(err as Error).message}`);
+    return 1;
+  }
+}
+
+async function inviteCmd(args: string[]): Promise<number> {
+  const identifier = args.filter((a) => !a.startsWith('-'))[0];
+  if (!identifier) {
+    console.error('usage: athsra org invite <identifier> [--role=member|admin]');
+    return 2;
+  }
+  let role: 'member' | 'admin' = 'member';
+  for (const a of args) {
+    if (a.startsWith('--role=')) {
+      const v = a.slice('--role='.length);
+      if (v !== 'member' && v !== 'admin') {
+        console.error('--role must be member|admin');
+        return 2;
+      }
+      role = v;
+    }
+  }
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  try {
+    const res = await ctx.client.inviteMember({ identifier, role });
+    const jit = res.jit_created ? ' — 신규 계정 생성' : '';
+    console.log(`✓ invited #${res.user_id} (${res.role}, ${res.status})${jit}`);
+    console.log(
+      '  초대받은 사람: athsra login → `athsra org ls` 에 pending 표시 → `athsra org use` 로 수락',
+    );
+    return 0;
+  } catch (err) {
+    const msg = (err as Error).message;
+    if (msg.includes('limit_exceeded')) {
+      console.error('✗ seat 한도 초과 — owner 가 plan upgrade 필요');
+    } else if (msg.includes('disabled')) {
+      console.error('✗ 비활성 계정은 초대 불가');
+    } else if (msg.includes('already a member')) {
+      console.error('✗ 이미 멤버');
+    } else if (msg.includes('pending')) {
+      console.error('✗ 이미 초대 대기 중');
+    } else if (msg.includes('403')) {
+      console.error('✗ owner/admin 만 초대 가능');
+    } else {
+      console.error(`✗ invite failed: ${msg}`);
+    }
+    return 1;
+  }
+}
+
+async function removeCmd(args: string[]): Promise<number> {
+  const userId = Number(args[0]);
+  if (!Number.isInteger(userId) || userId <= 0) {
+    console.error('usage: athsra org remove <user_id>  (athsra org members 로 user_id 확인)');
+    return 2;
+  }
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  try {
+    const res = await ctx.client.removeMember(userId);
+    console.log(`✓ removed #${res.user_id} (revoked, ${res.revoked_tokens} token(s) cleared)`);
+    // real revocation — DEK 회전(제거 멤버의 캐시 DEK 무효화). owner 만 가능(master 재wrap).
+    const role = await currentOrgRole(ctx);
+    if (role === 'owner') {
+      const rot = await rotateAfterRemoval(ctx.client, ctx.masterPw, userId);
+      reportRotation(rot);
+      return rot.failed.length > 0 ? 1 : 0;
+    }
+    console.log(
+      `  ⚠ DEK 회전은 owner 만 가능 — owner 가 \`athsra org rotate-after-removal ${userId}\` 실행 필요.`,
+    );
+    return 0;
+  } catch (err) {
+    const msg = (err as Error).message;
+    if (msg.includes('owner')) {
+      console.error('✗ org owner 는 제거 불가');
+    } else if (msg.includes('403')) {
+      console.error('✗ owner/admin 만 타인 제거 가능');
+    } else {
+      console.error(`✗ remove failed: ${msg}`);
+    }
+    return 1;
+  }
+}
+
+async function rotateAfterRemovalCmd(args: string[]): Promise<number> {
+  const userId = Number(args[0]);
+  if (!Number.isInteger(userId) || userId <= 0) {
+    console.error('usage: athsra org rotate-after-removal <user_id>  (제거된 멤버의 user_id)');
+    return 2;
+  }
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  const role = await currentOrgRole(ctx);
+  if (role !== 'owner') {
+    console.error('✗ DEK 회전은 현재 org 의 owner 만 가능합니다 (master pw 로 재wrap).');
+    return 1;
+  }
+  try {
+    const rot = await rotateAfterRemoval(ctx.client, ctx.masterPw, userId);
+    console.log(`✓ rotate-after-removal #${userId}`);
+    reportRotation(rot);
+    return rot.failed.length > 0 ? 1 : 0;
+  } catch (err) {
+    console.error(`✗ rotate failed: ${(err as Error).message}`);
+    return 1;
+  }
+}
+
+async function useCmd(args: string[]): Promise<number> {
+  const target = args[0];
+  if (!target) {
+    console.error('usage: athsra org use <slug|id>');
+    return 2;
+  }
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  const { orgs } = await ctx.client.listOrgs();
+  const org = orgs.find((o) => o.slug === target || String(o.id) === target);
+  if (!org) {
+    console.error(`✗ '${target}' org 멤버 아님 (athsra org ls 로 확인)`);
+    return 1;
+  }
+  try {
+    const sw = await ctx.client.switchOrg(org.id);
+    setToken(ctx.config.machineId, sw.token);
+    saveConfig({ ...ctx.config, orgId: sw.org_id, orgSlug: org.slug });
+    console.log(`✓ now acting as org ${org.slug} (${sw.role})`);
+    return 0;
+  } catch (err) {
+    const msg = (err as Error).message;
+    if (msg.includes('limit_exceeded')) {
+      console.error('✗ seat 한도 초과 — owner 가 plan upgrade 필요');
+    } else {
+      console.error(`✗ switch failed: ${msg}`);
+    }
+    return 1;
+  }
+}
+
+async function leaveCmd(): Promise<number> {
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  const me = await ctx.client.whoami();
+  if (me.userId === undefined) {
+    console.error('✗ token 에 user_id 없음 — athsra login');
+    return 1;
+  }
+  try {
+    await ctx.client.removeMember(me.userId);
+    // self-leave 가 현재 org token 을 삭제 → config.orgId clear (다음 명령의 idle-refresh 가
+    // personal org 로 re-register). personal 컨텍스트 복귀.
+    saveConfig({ ...ctx.config, orgId: undefined, orgSlug: undefined });
+    console.log('✓ left the org — personal 컨텍스트로 복귀 (다음 명령에서 자동 재인증).');
+    return 0;
+  } catch (err) {
+    const msg = (err as Error).message;
+    if (msg.includes('owner')) {
+      console.error('✗ owner 는 탈퇴 불가 (소유 이양 / org 삭제 필요)');
+    } else {
+      console.error(`✗ leave failed: ${msg}`);
+    }
+    return 1;
+  }
+}
+
+async function grantAccessCmd(args: string[]): Promise<number> {
+  const target = args.filter((a) => !a.startsWith('-'))[0];
+  const replace = args.includes('--replace');
+  if (!target) {
+    console.error('usage: athsra org grant-access <identifier|user_id> [--replace]');
+    return 2;
+  }
+  const ctx = await userCtx();
+  if (!ctx) return 1;
+  // identifier → 현재 org 멤버에서 user_id 해석 (숫자면 그대로).
+  let userId = Number(target);
+  if (!Number.isInteger(userId) || userId <= 0) {
+    const { members } = await ctx.client.listOrgMembers();
+    const member = members.find((x) => x.identifier === target);
+    if (!member) {
+      console.error(`✗ '${target}' 는 현재 org 멤버 아님 (athsra org members 로 확인)`);
+      return 1;
+    }
+    userId = member.user_id;
+  }
+  try {
+    // --replace: key reset 후 stale recipient 교체 (제거 후 새 pubkey 로 재포장).
+    const res = await grantOrgAccess(ctx.client, ctx.masterPw, userId, { replace });
+    const parts = [`granted ${res.granted.length}`, `skipped ${res.skipped.length}`];
+    if (res.legacyV1.length) parts.push(`v1 미지원 ${res.legacyV1.length}`);
+    if (res.failed.length) parts.push(`failed ${res.failed.length}`);
+    console.log(`✓ #${userId} re-wrap — ${parts.join(' · ')}`);
+    if (res.granted.length) console.log(`  공유: ${res.granted.join(', ')}`);
+    if (res.legacyV1.length) {
+      console.log(`  v1 envelope(먼저 \`athsra migrate-envelopes\`): ${res.legacyV1.join(', ')}`);
+    }
+    for (const f of res.failed) console.error(`  ✗ ${f.project}: ${f.error}`);
+    return res.failed.length > 0 ? 1 : 0;
+  } catch (err) {
+    console.error(`✗ grant-access failed: ${(err as Error).message}`);
+    return 1;
+  }
+}
+
+export async function orgCmd(args: string[]): Promise<number> {
+  const action = args[0];
+  switch (action) {
+    case 'create':
+      return createOrgCmd(args.slice(1));
+    case 'ls':
+    case 'list':
+      return lsOrgsCmd();
+    case 'members':
+      return membersCmd();
+    case 'invite':
+      return inviteCmd(args.slice(1));
+    case 'remove':
+      return removeCmd(args.slice(1));
+    case 'rotate-after-removal':
+      return rotateAfterRemovalCmd(args.slice(1));
+    case 'grant-access':
+      return grantAccessCmd(args.slice(1));
+    case 'use':
+    case 'switch':
+      return useCmd(args.slice(1));
+    case 'leave':
+      return leaveCmd();
+    default:
+      if (!action || action === '--help' || action === '-h') {
+        console.log(USAGE);
+        return action ? 0 : 2;
+      }
+      console.error(`Unknown action: ${action}`);
+      console.error(USAGE);
+      return 2;
+  }
+}

package/src/commands/rotate-master.ts

@@ -1,8 +1,16 @@
-import { deriveKey, fromBase64, toBase64 } from '@athsra/crypto';
+import {
+  deriveKey,
+  ENTERPRISE_KDF,
+  fromBase64,
+  isValidPhrase,
+  normalizePhrase,
+  toBase64,
+  wordCount,
+} from '@athsra/crypto';
 import { loadAuthContext, type UserAuthContext } from '../lib/auth-context.ts';
-import { isValidPhrase, normalizePhrase, wordCount } from '../lib/bip39.ts';
 import { AthsraClient } from '../lib/client.ts';
 import { readPlain, writePlain } from '../lib/envelope.ts';
+import { rewrapForRotation } from '../lib/identity-key.ts';
 import { setMasterPw, setToken } from '../lib/keyring.ts';
 import { promptConfirm, promptPassword } from '../lib/prompt.ts';
 
@@ -97,13 +105,20 @@ export async function rotateMasterCmd(_args: string[]): Promise<number> {
     console.log(`  ✓ ${p} (${Object.keys(plain).length} keys)`);
   }
 
-  // 2. POST /auth/rotate-master
+  // 2. identity 키쌍 재포장 재료 계산 (있으면) — old pw 로 unwrap → new pw 로 wrap. proof 회전
+  //    요청에 실어 원자적 갱신(별도 PUT 의 부분실패 = privkey 고아화 제거). 키 보유 시 server 가 필수.
+  const keyRewrap = await rewrapForRotation(client, oldPw, newPw);
+  if (keyRewrap) {
+    console.log('• Re-wrapping identity keypair with new master pw (atomic with rotation)...');
+  }
+
+  // POST /auth/rotate-master
   console.log('\n• Rotating server-side proof + invalidating all tokens...');
   const info = await client.info();
   const globalSalt = fromBase64(info.global_salt);
   const oldProof = toBase64(deriveKey(oldPw, globalSalt));
   const newProof = toBase64(deriveKey(newPw, globalSalt));
-  const rot = await client.rotateMaster(oldProof, newProof);
+  const rot = await client.rotateMaster(oldProof, newProof, keyRewrap ?? undefined);
   console.log(`  ✓ new token issued (machineId=${rot.machineId})`);
 
   // 3. keyring 갱신 + 새 client
@@ -120,15 +135,19 @@ export async function rotateMasterCmd(_args: string[]): Promise<number> {
 
   // 4. re-encrypt + PUT (v2 envelope, 자동 마이그레이션)
   console.log(
-    `\n• Re-encrypting ${Object.keys(plaintexts).length} projects with new master pw (as v2)...`,
+    `\n• Re-encrypting ${Object.keys(plaintexts).length} projects with new master pw ` +
+      '(v2, Argon2id m=256MB enterprise)...',
   );
   for (const [p, plain] of Object.entries(plaintexts)) {
-    await writePlain(newCtx, p, plain);
+    // rotate-master = enterprise KDF 마이그레이션 지점 (m=256MB). 이후 routine set 은
+    // writePlain 의 보존 로직으로 256MB 유지 (silent downgrade 없음).
+    await writePlain(newCtx, p, plain, { kdfParams: ENTERPRISE_KDF });
     console.log(`  ✓ ${p}`);
   }
 
   console.log(
-    `\n✓ master password rotated. ${Object.keys(plaintexts).length} projects re-encrypted as v2.`,
+    `\n✓ master password rotated. ${Object.keys(plaintexts).length} projects re-encrypted ` +
+      'as v2 (Argon2id m=256MB).',
   );
   console.log(
     '  service token recipients (있다면) 손실 — `athsra service-token create` 로 재발급 필요.',

package/src/commands/run.ts

@@ -30,7 +30,8 @@ export async function runCmd(args: string[]): Promise<number> {
     return 2;
   }
 
-  const ctx = await loadAuthContext();
+  // project 전달 — device-login agent (master pw 없는 머신) 의 project-scoped token 해석.
+  const ctx = await loadAuthContext(project);
   if (!ctx) return 1;
 
   const plain = await readPlain(ctx, project);

package/src/commands/service-token.ts

@@ -1,6 +1,10 @@
 import { addServiceRecipient, migrateV1ToV2, type SecretEnvelopeV2 } from '@athsra/crypto';
 import { loadAuthContext } from '../lib/auth-context.ts';
 import { resolveProject } from '../lib/auto-project.ts';
+import { red, yellow } from '../lib/colors.ts';
+
+/** worker expiry-notify (apps/worker/src/queue/expiry-notify.ts) 의 최임박 threshold 와 동기. */
+const EXPIRING_SOON_DAYS = 14;
 
 const USAGE = [
   'usage:',
@@ -158,12 +162,19 @@ async function listCmd(args: string[]): Promise<number> {
   console.log('');
   const now = Date.now();
   for (const t of tokens) {
-    const expired = t.expires_at && new Date(t.expires_at).getTime() < now;
-    const expiresLabel = t.expires_at
-      ? expired
-        ? `expired ${t.expires_at}`
-        : `expires ${t.expires_at}`
-      : 'no expiry';
+    let expiresLabel: string;
+    if (!t.expires_at) {
+      expiresLabel = 'no expiry';
+    } else {
+      const daysLeft = Math.ceil((new Date(t.expires_at).getTime() - now) / 86_400_000);
+      if (daysLeft <= 0) {
+        expiresLabel = red(`expired ${t.expires_at}`);
+      } else if (daysLeft <= EXPIRING_SOON_DAYS) {
+        expiresLabel = yellow(`expires ${t.expires_at} (${daysLeft}일 남음)`);
+      } else {
+        expiresLabel = `expires ${t.expires_at} (${daysLeft}일 남음)`;
+      }
+    }
     console.log(`  ${t.label}`);
     console.log(`    project:      ${t.project}`);
     console.log(`    perms:        ${t.perms}`);

package/src/index.ts

@@ -5,6 +5,7 @@ import { auditCmd } from './commands/audit.ts';
 import { completionCmd } from './commands/completion.ts';
 import { deleteCmd } from './commands/delete.ts';
 import { doctorCmd } from './commands/doctor.ts';
+import { drCmd } from './commands/dr.ts';
 import { getCmd } from './commands/get.ts';
 import { handoffCmd } from './commands/handoff.ts';
 import { initCmd } from './commands/init.ts';
@@ -15,6 +16,7 @@ import { manifestCmd } from './commands/manifest.ts';
 import { mcpCmd } from './commands/mcp.ts';
 import { migrateEnvelopesCmd } from './commands/migrate-envelopes.ts';
 import { newPhraseCmd } from './commands/new-phrase.ts';
+import { orgCmd } from './commands/org.ts';
 import { purgeCmd } from './commands/purge.ts';
 import { restoreCmd } from './commands/restore.ts';
 import { revokeCmd } from './commands/revoke.ts';
@@ -43,9 +45,11 @@ const commands: Record<string, (args: string[]) => Promise<number>> = {
   doctor: doctorCmd,
   'service-token': serviceTokenCmd,
   audit: auditCmd,
+  dr: drCmd,
   users: usersCmd,
   role: roleCmd,
   project: projectCmd,
+  org: orgCmd,
   'migrate-envelopes': migrateEnvelopesCmd,
   'rotate-master': rotateMasterCmd,
   'new-phrase': newPhraseCmd,
@@ -85,6 +89,7 @@ Usage:
   athsra users {list|invite <id> [--role=R]}  RBAC: user 목록 / 신규 invite (admin role 필요)
   athsra role {grant|revoke} <user_id> <R>    role 부여/제거 (admin/dev/viewer/auditor/sa)
   athsra project {share|unshare} <p> <uid>    per-project ACL share/unshare (--perms=read|write)
+  athsra org {create|ls|members|invite|remove|use|leave}  멀티테넌시 org 관리 + 컨텍스트 전환
   athsra migrate-envelopes [--apply]        모든 v1 envelope → v2 일괄 마이그레이션 (idempotent)
 
   athsra versions <project>                 모든 version + tombstone 상태
@@ -93,6 +98,8 @@ Usage:
   athsra restore <project>                  tombstone 제거 + 최신 version 활성화
   athsra purge <project>                    hard-delete (delete --hard 별칭, double-confirm)
 
+  athsra dr {restore-r2|restore-d1}         DR 복원 (backup→STORE / 암호화 D1 dump). dry-run 기본, --execute --confirm
+
   athsra rotate-master                      master pw 변경 (모든 projects re-encrypt)
   athsra new-phrase                         BIP-39 12-word phrase 생성 (master pw 권장)
   athsra handoff [--accept]                 새 머신 추가 (issue / accept)

package/src/lib/auth-context.ts

@@ -1,6 +1,7 @@
+import { deriveKey, fromBase64, toBase64 } from '@athsra/crypto';
 import { AthsraClient } from './client.ts';
 import { type Config, loadConfig } from './config.ts';
-import { getMasterPw, getToken } from './keyring.ts';
+import { getDeviceToken, getMasterPw, getToken, setToken } from './keyring.ts';
 
 /** User token mode — keyring 의 master pw + Bearer token 보유, full access. */
 export interface UserAuthContext {
@@ -41,42 +42,94 @@ export type AuthContext = UserAuthContext | ServiceAuthContext;
  *
  * 실패 시 stderr 에 안내 + null 반환. 호출자는 `return 1` 만.
  */
-export async function loadAuthContext(): Promise<AuthContext | null> {
+export async function loadAuthContext(project?: string): Promise<AuthContext | null> {
+  // 1. service token env (CI/headless 명시) — 최우선
   const envToken = process.env.ATHSRA_TOKEN;
   if (envToken?.startsWith('ats_')) {
     return loadServiceContext(envToken);
   }
-  return loadUserContext();
+  // 2. user context (master pw + token, full access) — 보유 시 우선
+  const userCtx = loadUserContext();
+  if (userCtx) return userCtx;
+  // 3. project-scoped device token (device-login agent) — master pw 없는 머신
+  //    Phase 3 P3: `athsra login --device --project <p>` 가 keyring 에 저장한 ats_*.
+  if (project) {
+    const deviceToken = getDeviceToken(project);
+    if (deviceToken?.startsWith('ats_')) {
+      const svc = await loadServiceContext(deviceToken, { silent: true });
+      if (svc) return svc;
+      console.error(
+        `device token for "${project}" 무효 (만료/revoke). ` +
+          `\`athsra login --device --project ${project}\` 로 재발급 (또는 \`athsra login\`).`,
+      );
+      return null;
+    }
+  }
+  // 4. 아무 자격증명 없음 — 안내
+  console.error(
+    project
+      ? `Not authenticated for "${project}". \`athsra login\` (full) 또는 ` +
+          `\`athsra login --device --project ${project}\` (agent, master pw 불필요).`
+      : 'Not logged in. Run `athsra login` first.',
+  );
+  return null;
 }
 
+/** master pw + token 보유 시 user context. 미보유 시 조용히 null (호출자가 device/안내 처리). */
 function loadUserContext(): UserAuthContext | null {
   const config = loadConfig();
-  if (!config) {
-    console.error('Not logged in. Run `athsra login` first.');
-    return null;
-  }
+  if (!config) return null;
   const masterPw = getMasterPw(config.machineId);
   const token = getToken(config.machineId);
-  if (!masterPw || !token) {
-    console.error('keyring missing master pw / token. Run `athsra login` first.');
-    return null;
-  }
+  if (!masterPw || !token) return null;
+  const client = new AthsraClient(config.workerUrl, token);
+  // Phase 3 — idle timeout 자동 재인증. 401 session_idle_timeout 시 keyring master pw
+  // 로 silent re-register (proof = Argon2id(pw + GLOBAL_SALT)) → 새 token keyring 저장.
+  // 기기 잠금 (OS keyring 차단) 이 방어선이므로 작업 중엔 끊김 없이, 잠금 시엔 idle 유효.
+  client.setIdleRefresh(async () => {
+    try {
+      const info = await client.info();
+      const proof = toBase64(deriveKey(masterPw, fromBase64(info.global_salt)));
+      const reg = await client.register(proof, config.machineId);
+      let token = reg.token;
+      // Phase 4 Slice 6a — re-register 는 자기 personal org 로 token 발급. switch 상태였으면
+      // (config.orgId) 다시 그 org 로 전환 — 안 하면 idle 후 사용자 모르게 personal 컨텍스트로 reset.
+      if (config.orgId !== undefined) {
+        client.setToken(token);
+        try {
+          token = (await client.switchOrg(config.orgId)).token;
+        } catch {
+          // switch 실패 (멤버십 변경/org 삭제) — personal org token 유지 (다음 `org use` 로 복구).
+        }
+      }
+      setToken(config.machineId, token);
+      return token;
+    } catch {
+      return null; // refresh 실패 — 원 401 그대로 (athsra login 안내)
+    }
+  });
   return {
     kind: 'user',
     config,
     masterPw,
     token,
-    client: new AthsraClient(config.workerUrl, token),
+    client,
   };
 }
 
-async function loadServiceContext(token: string): Promise<ServiceAuthContext | null> {
+async function loadServiceContext(
+  token: string,
+  opts?: { silent?: boolean },
+): Promise<ServiceAuthContext | null> {
+  const silent = opts?.silent ?? false;
   const config = loadConfig(); // optional in service mode
   const workerUrl = process.env.ATHSRA_WORKER_URL ?? config?.workerUrl;
   if (!workerUrl) {
-    console.error(
-      'service token 모드인데 worker URL 모름. `ATHSRA_WORKER_URL=https://...` 환경변수 또는 `~/.athsra/config.json` 필요.',
-    );
+    if (!silent) {
+      console.error(
+        'service token 모드인데 worker URL 모름. `ATHSRA_WORKER_URL=https://...` 환경변수 또는 `~/.athsra/config.json` 필요.',
+      );
+    }
     return null;
   }
   const client = new AthsraClient(workerUrl, token);
@@ -84,7 +137,9 @@ async function loadServiceContext(token: string): Promise<ServiceAuthContext | n
   try {
     me = await client.whoami();
   } catch (err) {
-    console.error(`service token 검증 실패 (worker /auth/whoami): ${(err as Error).message}`);
+    if (!silent) {
+      console.error(`service token 검증 실패 (worker /auth/whoami): ${(err as Error).message}`);
+    }
     return null;
   }
   if (
@@ -93,7 +148,11 @@ async function loadServiceContext(token: string): Promise<ServiceAuthContext | n
     (me.scopePerms !== 'read' && me.scopePerms !== 'write') ||
     !me.recipientId
   ) {
-    console.error('whoami 응답에 service token scope 정보 없음 — worker 갱신 필요 (Phase 1.x.8+).');
+    if (!silent) {
+      console.error(
+        'whoami 응답에 service token scope 정보 없음 — worker 갱신 필요 (Phase 1.x.8+).',
+      );
+    }
     return null;
   }
   return {