Vaultwarden (AXE vault)

AXE 플랫폼의 모든 서비스 비밀의 canonical store (D-ops-9). frame · hive · blueprint · stream · magnet 의 DB password · OAuth client_secret · JWT signing key · 외부 API token 이 전부 여기에 산다. 서비스 컨테이너는 vault 를 직접 모르고, axe ship / axe secret pull 이 배포 직전 vault → env_file 로 동기화한 뒤 docker compose 가 그 파일을 읽는다 (D-ops-17, runtime vault 호출 없음).

동시에 Microsoft Entra ID OIDC RP 로서 직원이 SSO 로 로그인하는 password manager 이기도 하다 — 즉 운영자용 secret CLI 백엔드 + 직원용 password vault 두 역할을 한 인스턴스가 겸한다.

본 페이지는 서비스 정의 (image · compose · env · org 모델 · 비밀 흐름). 직원 setup 절차는 /onboard/vault-setup, 운영자 비밀 매니페스트 흐름은 /architecture/secrets, 기존 vault 보유 customer 통합은 /partner/deploy § Vault OIDC SSO 통합 를 참조.

한눈에

이미지 — Timshel fork + axe.2 / axe.3 patch

upstream Vaultwarden (dani-garcia) 가 아니라 Timshel fork (native SSO 지원) 을 base 로, AXE 가 자체 patch 를 얹어 ghcr.io/axelabs-ai/vault 로 빌드한다 (D-ops-37 — fork build, D-ops-40 — axe.3 release).

• base: Timshel 1.34.1-6 (commit 80439605, 2025-07-15)
• axe.2 patch (Bitwarden client ≥ 2026.4 unlock 호환, dani-garcia mainline 에서 backport):
  1. /accounts/prelogin/password alias 추가 — 신 client 가 prelogin 을 password-only sub-endpoint 로 분리하는데 Timshel 은 legacy /accounts/prelogin 만 노출 → 404 → 로그인 실패
  2. /identity/connect/token 에 AccountKeys / MasterPasswordUnlock wrapped-variant 필드 backport — 없으면 unlock 시 Cannot read properties of null (reading toWrappedAccountCryptographicState)
• axe.3 patch (org permission quirk, 자체 진단): 3. src/api/core/organizations.rs 3곳의 if member.access_all { continue; } skip 제거 — Owner 는 access_all=true 라 explicit users_collections row 가 안 생겨 downstream permission 체크 (cipher delete) 가 깨졌음 4. Cipher::to_json 에 cipher.permissions {response, delete, restore} 필드 backport — client ≥ 2026.4 가 delete/restore 를 이 필드로 gate. can_delete = collection manage flag OR org Owner/Admin

axe.2 = KDF cutoff. axe.2 release (2026-05-26) 이전 가입 user 는 옛 schema (client_kdf_type=0, PBKDF2) 라 SSO→MP unlock 이 toWrappedAccountCryptographicState 에러로 막혀 KDF rotation (PBKDF2 → Argon2id) 이 필요하다 (D-ops-40 runbook, axe-side 4명 ai/soohun/taehun/jinwoo). axe.2 이후 신규 가입 user (realchoice 측 등) 는 새 schema 로 가입돼 rotation 불필요. 상세 = /onboard/vault-setup § KDF rotation.

pin / rollback

• source build: axelabs-ai/vault repo 의 build/build.sh + .github/workflows/build.yml (GHA, buildx multi-arch linux/amd64 + linux/arm64), commit 799015b.
• GHCR auth: ghcr.io/axelabs-ai/vault 는 private. pull PAT 는 vault 의 Platform — Service Secrets / ghcr-axelabs-ai-pull-pat 에 보관 (값은 vault 안). docker login:

  bw get password ghcr-axelabs-ai-pull-pat | docker login ghcr.io -u axe-labs-ai --password-stdin

• upstream PR (저우선): axe.3 patch 3+4 를 Timshel 에 제출 — accept 되면 자체 diff 소멸.

compose / 포트

/Users/axe/.axe/vault/docker-compose.yml — 2 컨테이너:

• core 는 host 포트를 안 받는다 — expose: "80" 만 (컨테이너 네트워크 내부). Caddy 가 유일한 진입점.
• Caddy 는 127.0.0.1 에만 바인딩 (127.0.0.1:8222:443) — Tailnet/공개 노출 X. bw CLI (운영자 mac) 가 mkcert 로컬 인증서로 신뢰, 외부 직원은 cloudflared 터널 origin 으로만 닿는다.
• volume: core 는 ./data:/data (sqlite + attachments), Caddy 는 named volume 2개.

Caddy — sub-path 호스팅 함정

/Users/axe/.axe/vault/Caddyfile 는 :443 에서 모든 hostname 을 받는다 (localhost = bw CLI mkcert cert, axe.axelabs.ai = cloudflared origin, Host 보존). Vaultwarden 은 DOMAIN env 가 canonical URL 을 가리키는 한 Host mismatch 를 무시한다.

핵심은 trailing-slash redirect:

@vault_no_slash { path /vault }
redir @vault_no_slash /vault/ permanent
reverse_proxy axe-vaultwarden:80

Vaultwarden SPA 의 HTML 은 상대 asset 경로 (images/..., app/main.js) 를 쓴다. 사용자가 trailing slash 없는 /vault 로 들어오면 브라우저가 vault 를 파일로 보고 root 로 올라가 /app/main.js 를 요청 → cloudflared 가 default ingress (blueprint:3100) 로 보내 모든 static asset 이 502. /vault/ 강제 301 로 base directory 를 /vault/ 로 고정해야 한다. (customer 측 onboarding 함정 표에도 동일 항목 — /architecture/secrets.)

환경 변수

axe-vaultwarden.environment (값 일부는 ./.env, mode 600, gitignored 에서 치환):

${AZURE_TENANT_ID} / ${AZURE_VAULTWARDEN_APP_ID} / ${AZURE_VAULTWARDEN_CLIENT_SECRET} 는 /Users/axe/.axe/vault/.env (mode 600) 에서 치환된다. customer macmini 의 같은 4-key 패치 (SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION / SIGNUPS_ALLOWED / SSO_ONLY=false / ORGANIZATION_INVITE_AUTO_ACCEPT) 는 axe vault bootstrap {customer} 가 in-place 적용 (D-ops-33, customer-onboarding D+1).

Organization 모델

비밀과 직원 password 는 단일 AXE organization 안에 산다 (org UUID 0c5d8bbd-ad85-42b4-8b8a-2849031981b1, axe CLI _AXE_VAULT_ORG_ID, MCP catalog org 와 동일 UUID).

dual-identity 계정 (D-ops-29)

org 운영은 customer 당 두 종류 계정으로 나뉜다:

axe CLI 는 ai@ 계정의 BW_SESSION (macOS Keychain service=axe.vault.session, [email protected]) 으로 bw subprocess 를 돌린다. master password 는 출근 시 1회 bw unlock 후 Keychain 에 cache (8h) — 이후 모든 axe secret/axe vault 명령이 재입력 없이 동작.

⚠️ “axe.2 / axe.3” 는 org 계정 종류가 아니라 image patch release 다 (위 § 이미지). org 계정 모델은 위 dual-identity (ai@ bot + 사람 admin) 가 정답.

Collection 구조 v1 (D-ops-32)

별도로 MCP connector 카탈로그용 MCP Connectors collection (1a62e754-6e47-43e0-a99a-cf71c37b8638) 이 있다 — axe mcp publish 가 connector 메타를 여기에 쓰고, 직원이 claude.ai 에 connector 추가 시 이 collection 에서 값을 본다 (/onboard/claude-connectors, D-vault-mcp-catalog).

org REST 자동화는 axe CLI 가 bw-derived API token 으로 직접 호출한다 — axe vault org-invite (POST /api/organizations/{org_id}/users/invite), axe secret prompt-store (org collection 에 hidden-text item 생성, 값이 shell history/clipboard 에 안 남음).

비밀 흐름 — customers.yaml secrets[] → vault → axe secret pull

핵심 invariant: 서비스 코드는 vault 를 모른다. customers.yaml 의 services.<svc>.secrets[] 매니페스트가 env-var ↔ vault-item 매핑의 SSOT 이고, axe secret 명령들이 그 사이를 잇는다.

customers.yaml                         Vaultwarden (org)              service env_file
services.<svc>.secrets[]               ai@ 계정, bw CLI               <svc>/.env (mode 600)
  - env: FRAME_DB_PASSWORD    ──push──▶  item "frame/axe/db-password"  ──pull──▶ FRAME_DB_PASSWORD=...
    vault: frame/axe/db-password         (password 필드)                          (docker compose env_file)

vault item 네이밍 컨벤션: <service>/<customer>/<short> (예: frame/axe/db-password, blueprint/realchoice/azure-client-secret). 상세 + 전체 매니페스트 (현재 42개 비밀 등재) = /architecture/secrets.

자기 자신 비밀 — bootstrap_only

vault 의 자기 OAuth client_secret (AZURE_VAULTWARDEN_CLIENT_SECRET) 은 vault 자신이 자기를 못 읽는다 (vault 가 부팅돼야 secret 을 줄 수 있는데, 부팅에 그 secret 이 필요한 chicken-and-egg). 그래서 customers.yaml 에서 vaultwarden service 는 bootstrap_only: true — axe secret check/pull 이 skip 하고, /Users/axe/.axe/vault/.env 가 직접 그 값을 들고 있다 (vault 매니페스트엔 “manually maintained — vault is the SoT but can’t read itself” 주석).

즉 vaultwarden 의 SSO secret 1개만 매니페스트상 self-referential 예외이고, 나머지 모든 서비스 비밀은 정상 push/pull 경로를 탄다.

백업

vault 의 ./data (sqlite + attachments) 는 AXE 3-tier backup (local + ring + cold SSD, restic) 에 포함된다. 복구 절차는 vault master password 로 axe-vaultwarden 잠금 해제 후 data 복원 — 상세 = /architecture/backup.

함정

참고

• 운영자 비밀 매니페스트 + axe secret 명령: /architecture/secrets (D-ops-17)
• 직원 vault setup (SSO/KDF/3-client): /onboard/vault-setup
• 기존 vault 보유 customer 통합: /partner/deploy § Vault OIDC SSO 통합
• customer 측 vault bootstrap: /ops/runbook/customer-onboarding § D+1
• 결정: D-ops-9 · D-ops-10 · D-ops-17 · D-ops-24 · D-ops-26 · D-ops-27 · D-ops-28 · D-ops-32 · D-ops-33 · D-ops-37 · D-ops-40
• 소스: /Users/axe/.axe/vault/{docker-compose.yml, Caddyfile, .env} · build: axelabs-ai/vault repo