@athsra/cli 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 athsra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This license applies to the following packages:
+- packages/crypto
+- packages/cli (when added in Phase 0 Day 1 PM)
+- packages/sdk-* (when added in Phase 2)
+- integrations/* (when added in Phase 3+)
+
+Server code (apps/worker) is licensed separately under BSL 1.1 — see LICENSE-BSL.

package/README.md

@@ -0,0 +1,155 @@
+# @athsra/cli
+
+[athsra](https://github.com/modfolio/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+)
+
+```bash
+# Bun 설치 (없으면)
+curl -fsSL https://bun.sh/install | bash
+
+# CLI 설치
+bun add -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 계정에 배포:
+
+```bash
+gh repo clone modfolio/athsra ~/code/athsra
+cd ~/code/athsra && bun install
+bash scripts/setup-worker.sh    # R2 + KV + GLOBAL_SALT + deploy 멱등
+```
+
+### 2. 첫 머신 등록 (PROOF bootstrap)
+
+```bash
+# (권장) BIP-39 12-word recovery phrase 생성
+athsra new-phrase   # 12 단어 출력 → 종이에 정확히 적기
+
+athsra login
+# Worker URL: https://athsra-worker.<account>.workers.dev
+# Master password: <위 phrase 또는 자유 phrase>
+# Paper backup confirm: yes
+```
+
+### 3. 평소 사용
+
+```bash
+# 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)
+
+```bash
+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. 다른 머신 추가
+
+```bash
+# 기존 머신
+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
+```
+
+## 전체 명령
+
+| 명령 | 동작 |
+|---|---|
+| `athsra login` | 첫 등록 (PROOF bootstrap) |
+| `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` (KV ~60s eventual). master pw 모름 → 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](https://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](./LICENSE)
+
+Server (athsra-worker, BSL 1.1) 는 별도 license — see [main repo](https://github.com/modfolio/athsra).
+
+## Status
+
+**Phase 1.x.1 active** (2026-05-04+) — soft-delete + version history. universe internal alpha.
+
+[ROADMAP.md](https://github.com/modfolio/athsra/blob/main/docs/ROADMAP.md) — 남은 작업 + 미래 분기점 SSoT.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@athsra/cli",
+  "version": "0.1.0",
+  "description": "athsra CLI — E2EE secret manager on Cloudflare edge. Doppler-style dev UX + zero-knowledge encryption + soft-delete + version history. MIT.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "athsra": "./src/index.ts"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modfolio/athsra.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/modfolio/athsra",
+  "bugs": "https://github.com/modfolio/athsra/issues",
+  "keywords": [
+    "secret-manager",
+    "secrets",
+    "e2ee",
+    "encryption",
+    "argon2id",
+    "aes-256-gcm",
+    "cloudflare-workers",
+    "doppler-alternative",
+    "athsra"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": ["src/", "README.md", "LICENSE"],
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@athsra/crypto": "^0.1.0",
+    "@napi-rs/keyring": "^1.1.6",
+    "@scure/bip39": "^2.2.0",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^6.0.2"
+  }
+}

package/src/commands/delete.ts

@@ -0,0 +1,48 @@
+import { loadAuthContext } from '../lib/auth-context.ts';
+import { promptConfirm } from '../lib/prompt.ts';
+
+const USAGE = [
+  'usage: athsra delete <project>           # soft-delete (versions 보존, restore 가능)',
+  '   or: athsra delete <project> --hard    # hard-delete (모든 versions 영구 제거)',
+  '   or: athsra delete <project> --yes     # confirm 우회 (CI 용)',
+].join('\n');
+
+/**
+ * athsra delete <project>
+ *   - soft (default): tombstone marker 작성, versions 보존, restore 가능
+ *   - --hard: 모든 versions + tombstone 영구 제거. 복원 불가능.
+ *   - confirm 필요 (--yes 또는 ATHSRA_DELETE_CONFIRMED=1 로 우회)
+ */
+export async function deleteCmd(args: string[]): Promise<number> {
+  const project = args[0];
+  if (!project) {
+    console.error(USAGE);
+    return 2;
+  }
+  const hard = args.includes('--hard');
+  const yes = args.includes('--yes') || args.includes('-y');
+
+  const ctx = loadAuthContext();
+  if (!ctx) return 1;
+  const { client } = ctx;
+
+  if (!yes && process.env.ATHSRA_DELETE_CONFIRMED !== '1') {
+    const msg = hard
+      ? `HARD-DELETE ${project}? All version history permanently removed. NOT RECOVERABLE.`
+      : `Soft-delete ${project}? Restore via 'athsra restore ${project}'.`;
+    const ok = await promptConfirm(msg, false);
+    if (!ok) return 0;
+  }
+
+  const result = await client.deleteProject(project, { hard });
+  if (hard) {
+    console.log(
+      `✓ ${project}: hard-deleted (${result.removed_versions ?? 0} version${(result.removed_versions ?? 0) === 1 ? '' : 's'} removed)`,
+    );
+  } else {
+    console.log(
+      `✓ ${project}: soft-deleted (${result.recoverable_versions ?? 0} version${(result.recoverable_versions ?? 0) === 1 ? '' : 's'} recoverable via 'athsra restore')`,
+    );
+  }
+  return 0;
+}

package/src/commands/doctor.ts

@@ -0,0 +1,76 @@
+import { existsSync } from 'node:fs';
+import { AthsraClient } from '../lib/client.ts';
+import { CONFIG_FILE, loadConfig, SESSION_FILE } from '../lib/config.ts';
+import { getMasterPw, getToken, probeKeyring } from '../lib/keyring.ts';
+
+export async function doctorCmd(_args: string[]): Promise<number> {
+  console.log('athsra doctor\n');
+
+  const kr = probeKeyring();
+  console.log(`  keyring backend:  ${kr.ok ? '✓ OK' : `✗ ${kr.error ?? 'unknown'}`}`);
+  if (!kr.ok) {
+    console.log('    setup (WSL2/Linux):');
+    console.log('      sudo apt update && sudo apt install gnome-keyring libsecret-1-dev dbus-x11');
+    console.log('      eval $(dbus-launch --sh-syntax)   # if DBUS_SESSION_BUS_ADDRESS missing');
+    console.log('    macOS / Windows: 자동 (Keychain / Credential Manager)');
+  }
+  console.log(
+    `  DBUS_SESSION_BUS_ADDRESS: ${process.env.DBUS_SESSION_BUS_ADDRESS ? '✓ present' : '✗ missing'}`,
+  );
+
+  const config = loadConfig();
+  console.log(`  config:           ${existsSync(CONFIG_FILE) ? '✓' : '✗'} ${CONFIG_FILE}`);
+  if (!config) {
+    console.log('  (run `athsra login` first)');
+    return kr.ok ? 0 : 1;
+  }
+  console.log(`  worker:           ${config.workerUrl}`);
+  console.log(`  machine:          ${config.machineId}`);
+  console.log(`  created:          ${config.createdAt}`);
+
+  if (existsSync(SESSION_FILE)) {
+    console.log(`  ⚠ legacy:        ${SESSION_FILE} 잔존 (next \`athsra login\` 시 자동 제거).`);
+  }
+
+  const masterPw = kr.ok ? getMasterPw(config.machineId) : null;
+  const token = kr.ok ? getToken(config.machineId) : null;
+  console.log(`  master-pw (keyring): ${masterPw ? '✓ present' : '✗ missing'}`);
+  console.log(`  token     (keyring): ${token ? '✓ present' : '✗ missing'}`);
+
+  const client = new AthsraClient(config.workerUrl, token);
+  const reachable = await client.health();
+  console.log(`  worker reachable: ${reachable ? '✓' : '✗'}`);
+  if (!reachable) return 1;
+
+  try {
+    const info = await client.info();
+    console.log(`  worker phase:     ${info.phase}`);
+    console.log(`  global_salt v${info.global_salt_version}: ${info.global_salt.slice(0, 12)}…`);
+    if (info.phase < 1) {
+      console.log('  ⚠ phase < 1 — Pre-A 인증 미배포 상태.');
+    }
+  } catch (err) {
+    console.log(`  info: error — ${(err as Error).message}`);
+  }
+
+  if (token) {
+    try {
+      const me = await client.whoami();
+      console.log(`  whoami:           machineId=${me.machineId} lastSeenAt=${me.lastSeenAt}`);
+    } catch (err) {
+      console.log(`  whoami:           ✗ ${(err as Error).message}`);
+    }
+    try {
+      const projects = await client.listProjects();
+      const head = projects.slice(0, 5).join(', ');
+      const more = projects.length > 5 ? ', …' : '';
+      console.log(
+        `  projects:         ${projects.length}${projects.length ? ` (${head}${more})` : ''}`,
+      );
+    } catch (err) {
+      console.log(`  projects:         fetch error — ${(err as Error).message}`);
+    }
+  }
+
+  return kr.ok && reachable ? 0 : 1;
+}

package/src/commands/get.ts

@@ -0,0 +1,40 @@
+import { decrypt, deriveKey, fromBase64 } from '@athsra/crypto';
+import { loadAuthContext } from '../lib/auth-context.ts';
+import { parseEnv } from '../lib/env-format.ts';
+
+export async function getCmd(args: string[]): Promise<number> {
+  const project = args[0];
+  const key = args[1];
+  if (!project) {
+    console.error('usage: athsra get <project> [KEY]');
+    return 2;
+  }
+
+  const ctx = loadAuthContext();
+  if (!ctx) return 1;
+  const { masterPw, client } = ctx;
+  const envelope = await client.getEnvelope(project);
+  if (!envelope) {
+    console.error(`project not found: ${project}`);
+    return 1;
+  }
+
+  const derived = deriveKey(masterPw, fromBase64(envelope.salt));
+  const text = await decrypt(derived, {
+    ciphertext: fromBase64(envelope.ciphertext),
+    nonce: fromBase64(envelope.nonce),
+  });
+
+  if (key) {
+    const plain = parseEnv(text);
+    const value = plain[key];
+    if (value === undefined) {
+      console.error(`key not found: ${key}`);
+      return 1;
+    }
+    console.log(value);
+  } else {
+    console.log(text);
+  }
+  return 0;
+}

package/src/commands/handoff.ts

@@ -0,0 +1,138 @@
+import { hostname } from 'node:os';
+import { deriveKey, fromBase64, toBase64 } from '@athsra/crypto';
+import { loadAuthContext } from '../lib/auth-context.ts';
+import { AthsraClient } from '../lib/client.ts';
+import { type Config, saveConfig } from '../lib/config.ts';
+import { probeKeyring, setMasterPw, setToken } from '../lib/keyring.ts';
+import { promptPassword, promptText } from '../lib/prompt.ts';
+
+const USAGE = [
+  'usage: athsra handoff               — 새 머신 등록 token 발급 (기존 머신에서 실행)',
+  '   or: athsra handoff --accept     — 발급된 token + master pw 로 새 머신 셋업',
+].join('\n');
+
+async function issueToken(): Promise<number> {
+  console.log('athsra handoff (issue, 기존 머신에서)\n');
+  const ctx = loadAuthContext();
+  if (!ctx) return 1;
+  const { masterPw, client } = ctx;
+
+  const newLabel = await promptText('New machine label (예: home-desktop)');
+  if (!newLabel) {
+    console.error('label required');
+    return 1;
+  }
+
+  const info = await client.info();
+  const proof = toBase64(deriveKey(masterPw, fromBase64(info.global_salt)));
+  const result = await client.handoff(proof, newLabel);
+
+  const ttlMin = result.ttlSeconds ? Math.floor(result.ttlSeconds / 60) : null;
+  console.log('\n✓ Handoff token issued.');
+  if (ttlMin) {
+    console.log(`  ⏰ TTL: ${ttlMin} min (single-use 등록 grace period)`);
+    if (result.expiresAt) console.log(`  expires: ${result.expiresAt}`);
+  }
+  console.log('\n새 머신에서 다음 명령 실행:');
+  console.log(`\n  ATHSRA_HANDOFF_TOKEN='${result.token}' \\`);
+  console.log(`  ATHSRA_HANDOFF_MACHINE='${result.machineId}' \\`);
+  console.log(`  ATHSRA_WORKER_URL='${client.workerUrl}' \\`);
+  console.log('  bun packages/cli/src/index.ts handoff --accept');
+  console.log('\n  (master password 도 새 머신에서 한 번 입력해야 keyring 저장 가능)');
+  console.log('  (TTL 안에 사용 안 하면 token 자동 만료 — handoff 다시 발급 필요)');
+  return 0;
+}
+
+async function acceptToken(): Promise<number> {
+  console.log('athsra handoff --accept (새 머신 셋업)\n');
+
+  const probe = probeKeyring();
+  if (!probe.ok) {
+    console.error(`✗ keyring backend unavailable: ${probe.error ?? 'unknown'}`);
+    console.error('  Run `athsra doctor` for setup instructions.');
+    return 1;
+  }
+
+  const token = process.env.ATHSRA_HANDOFF_TOKEN ?? (await promptText('Handoff token (atk_*)'));
+  if (!token.startsWith('atk_')) {
+    console.error('Invalid token format (must start with atk_)');
+    return 1;
+  }
+  const machineId =
+    process.env.ATHSRA_HANDOFF_MACHINE ??
+    (await promptText('Machine label', `${hostname()}-${Date.now().toString(36)}`));
+  const workerUrl =
+    process.env.ATHSRA_WORKER_URL ??
+    (await promptText('Worker URL', 'https://athsra-worker.winterermod.workers.dev'));
+
+  // master pw 입력 (새 머신에서도 keyring 저장 필요 — set/get 시 sync 그 아래 envelope decrypt 위해)
+  const masterPw = process.env.ATHSRA_MASTER_PW ?? (await promptPassword('Master password'));
+  if (masterPw.length < 8) {
+    console.error('Master password too short');
+    return 1;
+  }
+
+  // worker reachability
+  const client = new AthsraClient(workerUrl, token);
+  const ok = await client.health();
+  if (!ok) {
+    console.error(`✗ worker unreachable: ${workerUrl}`);
+    return 1;
+  }
+
+  // whoami 로 token + master pw 동시 검증 (envelope decrypt round-trip)
+  let me: Awaited<ReturnType<typeof client.whoami>>;
+  try {
+    me = await client.whoami();
+  } catch (err) {
+    console.error(`✗ token invalid: ${(err as Error).message}`);
+    return 1;
+  }
+
+  // master pw 검증: 첫 envelope (있으면) decrypt 시도
+  const projects = await client.listProjects();
+  const first = projects[0];
+  if (first) {
+    const env = await client.getEnvelope(first);
+    if (env) {
+      try {
+        const key = deriveKey(masterPw, fromBase64(env.salt));
+        const { decrypt } = await import('@athsra/crypto');
+        await decrypt(key, {
+          ciphertext: fromBase64(env.ciphertext),
+          nonce: fromBase64(env.nonce),
+        });
+      } catch {
+        console.error('✗ master password mismatch — 옛 master pw 와 일치 X');
+        return 1;
+      }
+    }
+  }
+
+  // config + keyring 저장
+  const config: Config = {
+    workerUrl,
+    machineId,
+    createdAt: me.createdAt,
+  };
+  saveConfig(config);
+  setMasterPw(machineId, masterPw);
+  setToken(machineId, token);
+
+  console.log(`\n✓ Handoff accepted (machine: ${machineId}).`);
+  console.log(`  worker:   ${workerUrl}`);
+  console.log(`  whoami:   lastSeenAt=${me.lastSeenAt}`);
+  console.log(`  projects: ${projects.length}`);
+  return 0;
+}
+
+export async function handoffCmd(args: string[]): Promise<number> {
+  if (args[0] === '--help' || args[0] === '-h') {
+    console.log(USAGE);
+    return 0;
+  }
+  if (args[0] === '--accept') {
+    return acceptToken();
+  }
+  return issueToken();
+}

package/src/commands/init.ts

@@ -0,0 +1,11 @@
+export async function initCmd(args: string[]): Promise<number> {
+  const project = args[0];
+  if (!project) {
+    console.error('usage: athsra init <project>');
+    return 2;
+  }
+  console.log(`Phase 0: project '${project}' is created on first \`athsra set\`.`);
+  console.log('No metadata registration needed in Phase 0.');
+  console.log(`\nNext: athsra set ${project} KEY=value`);
+  return 0;
+}