@athsra/cli

@athsra/cli

athsra — E2EE secret manager on Cloudflare edge. Doppler 의 dev UX + zero-knowledge encryption + Cloudflare 글로벌 edge <50ms latency.

Brand: 한국어 "아스라이" (어렴풋이) 어원, 발음 Ah-sra.

핵심 가치

• Zero-knowledge E2EE — server (CF Worker) 는 ciphertext + Argon2id proof 만, master password 절대 X
• Self-hosted — 본인 Cloudflare 계정 (R2 + KV + Workers, free tier 충분)
• Doppler-style — athsra run <project> -- <cmd> 으로 env inject 후 명령 실행
• Soft-delete + version history — 모든 PUT 은 immutable version 보존, DELETE 는 default soft (restore 가능)
• Cross-machine — handoff TTL + single-use settle 로 새 머신 추가
• BIP-39 12-word phrase — master pw 권장 형식 (paper backup + checksum)

설치 (prereq: Bun 1.3+)

# Bun 설치 (없으면)
curl -fsSL https://bun.sh/install | bash

# CLI 설치
bun add -g @athsra/cli
# 또는
npm i -g @athsra/cli

Bun runtime 강제 — TypeScript 직접 실행 + native crypto 성능. Node 호환은 후속 버전.

Linux/WSL2: gnome-keyring + libsecret-1-dev + dbus-x11 필요. macOS/Windows 자동 (Keychain / Cred Manager).

Quick start

1. Worker 배포 (1머신 1회)

athsra-worker 를 본인 CF 계정에 배포:

gh repo clone modfolio/athsra ~/code/athsra
cd ~/code/athsra && bun install
bash scripts/setup-worker.sh    # R2 + KV + GLOBAL_SALT + deploy 멱등

2. 로그인

# 일반 머신/AI agent: 브라우저 device flow.
ATHSRA_WORKER_URL=https://athsra-worker.<account>.workers.dev athsra login
# URL + 코드 + 디바이스 지문 출력 → 브라우저에서 승인

# founding owner / 복구용 full-access 머신:
athsra new-phrase   # 12 단어 출력 → 종이에 정확히 적기
ATHSRA_WORKER_URL=https://athsra-worker.<account>.workers.dev athsra login --password

3. 평소 사용

# secret 추가 / 수정
athsra set my-app DATABASE_URL=postgres://...
athsra set my-app API_KEY=sk_xxx STRIPE_KEY=sk_yyy

# .env 형식 일괄 import
athsra set my-app --from-file .env

# 조회
athsra get my-app                # dump 모두 (.env 형식)
athsra get my-app DATABASE_URL   # 특정 key
athsra ls                        # project 목록
athsra ls my-app                 # key 이름 목록 (값 X)

# Doppler-style env inject
athsra run my-app -- bun run dev
athsra run my-app -- npm run build

4. 실수 복구 (Phase 1.x.1)

athsra versions my-app           # 모든 version + tombstone 상태
athsra rollback my-app v1234     # 특정 version 으로 current 복원
athsra delete my-app             # soft-delete (versions 보존)
athsra ls --all                  # 'my-app (deleted)' 표시
athsra restore my-app            # 최신 version 으로 활성화
athsra purge my-app              # 영구 삭제 (double-confirm)

원리: R2 secrets/<project>/{current,versions/<id>,tombstone}.json 3-tier layout. PUT 시 새 version + current 갱신 + tombstone 자동 제거 (auto-restore).

5. 다른 머신 추가

# 기존 머신
athsra handoff   # New machine label → handoff token (1h TTL, single-use)

# 새 머신
ATHSRA_HANDOFF_TOKEN='atk_...' \
ATHSRA_HANDOFF_MACHINE='home-desktop' \
ATHSRA_WORKER_URL='https://...' \
ATHSRA_MASTER_PW='<기존과 동일>' \
  athsra handoff --accept

MCP — AI agent 표면 (Claude Code / Cursor / VS Code)

npm 에서 이 패키지를 발견한 AI 에이전트라면: athsra 는 MCP 로 전 기능을 자율 조작하도록 설계됐다 — 평문 시크릿 값은 단 한 번도 에이전트에게 노출되지 않는다.

athsra mcp install --write --apply      # .mcp.json 등록 (dry-run 기본 — --apply 가 실제 변경)
# --client cursor|vscode  --scope user  --admin  지원

1. 인증은 채팅 안에서 — athsra_whoami → 미인증이면 athsra_login_start 호출 (터미널 불필요). 반환된 URL+코드+디바이스 지문을 사용자에게 전달 → 사용자가 브라우저에서 가입/로그인 + master password 로 승인 (master pw 는 브라우저 밖으로 안 나감) → athsra_login_status poll (retry_after 준수) → approved.
2. 3-tier 도구 27종:
   • read 12 (항상): whoami · login_start/status · list_projects · get_project_keys(키 이름만) · versions · audit · list_orgs · org_info · doctor · show/validate_manifest
   • write 8 (ATHSRA_MCP_WRITE=1): set_secret · unset_secret · bulk_set · rollback · delete_project(soft) · restore_project · manifest_init/modify
   • admin 7 (ATHSRA_MCP_ADMIN=1): org_invite · org_remove_member · project_share/unshare · service_token_create/revoke · purge — destructive 는 confirm 정확일치 필수
3. 값 무노출 원칙: 값 소비는 MCP 밖 athsra run <p> -- <cmd> 주입으로만. athsra get/run 은 의도적으로 MCP 도구가 아니다. 유일 예외 = athsra_service_token_create 의 1회성 ats_* 반환 (즉시 secret store 보관).

전체 가이드: athsra.com/ai · athsra.com/llms.txt

전체 명령

명령	동작
athsra login	브라우저 완결 identity 로그인 기본 (--password = founding master pw 등록, --sso, --device)
athsra mcp	MCP stdio server (AI agent 표면 — 위 섹션)
athsra mcp install	MCP client 설정 등록/갱신 (claude/cursor/vscode, dry-run 기본)
athsra service-token create/list/revoke	scoped headless 토큰 (NAS/CI — master pw 없이 복호)
athsra set <p> KEY=val [...]	secret 추가/수정 (--from-file / --stdin 지원)
athsra unset <p> KEY [...]	특정 key 제거 (envelope 유지)
athsra get <p> [KEY]	값 출력 (single 또는 dump)
athsra ls [<p>] [--all]	project 또는 key 목록
athsra run <p> -- <cmd>	env inject 후 명령 실행
athsra versions <p>	모든 version + tombstone 상태
athsra rollback <p> <vid>	특정 version 으로 current 복원
athsra delete <p> [--hard]	soft-delete (default) 또는 hard-delete
athsra restore <p>	tombstone 제거 + 최신 version 활성화
athsra purge <p>	hard-delete 별칭 (double-confirm)
athsra rotate-master	master pw 변경 (모든 envelope re-encrypt)
athsra new-phrase	BIP-39 12-word recovery phrase 생성
athsra handoff [--accept]	새 머신 추가
athsra revoke [<atk_*>]	self 또는 명시 token revoke
athsra doctor	환경 검증 (keyring/dbus/worker phase)
athsra init <p>	신규 project 안내

보안

위협	완화
R2 leak (CF 침해)	E2EE — ciphertext 만 노출. Argon2id m=64MB × t=3 brute-force 비용
token leak (머신 도난)	athsra revoke (D1 strong consistency). master pw 또는 identity key 없으면 decrypt 불가
handoff token 가로챔	TTL 1h + single-use settle (Phase 1.2)
master pw leak	rotate-master — 모든 PROOF/token 갱신 + 모든 envelope re-encrypt
master pw 분실	종이 backup 필수 + BIP-39 12-word phrase. recovery 없음 (E2EE 본질)
실수 삭제 / 덮어쓰기	soft-delete + version history (Phase 1.x.1) — restore/rollback 으로 복구
keyring leak	OS 자체 격리 (libsecret D-Bus / Keychain / Cred Manager DPAPI)

자세한 architecture + threat model: github.com/modfolio/athsra/blob/main/docs/ARCHITECTURE.md.

Cryptographic primitives

• Argon2id (memory-hard KDF) — PHC 2015 winner, OWASP 2024+ 1순위. m=64MB. @noble/hashes/argon2 (Cure53 부분 audit, 0 deps)
• AES-256-GCM — WebCrypto native. NIST SP 800-38D / FIPS 140-2 approved. nonce 12B per-envelope
• SHA-256 — WebCrypto subtle.digest (token hash)
• BIP-39 mnemonic — @scure/bip39 (paulmillr audited). 128-bit entropy + 4-bit checksum

License

MIT — LICENSE

Server (athsra-worker, BSL 1.1) 는 별도 license — see main repo.

Status

Phase 5 RC (2026-06-12) — identity device-login + MCP 27 tools + envelope member/self recipients. Published package target: @athsra/cli@1.1.0.

ROADMAP.md — 남은 작업 + 미래 분기점 SSoT.