Timshel/vaultwarden upstream PR draft — bw 2026.4+ client compatibility (2026-05)

상태: Draft. 운영자 검토 후 Timshel/vaultwarden  에 그대로 PR 본문으로 paste 가능한 self-contained 제출문.

Backlog: B-vault-axe.2-patches-upstream-pr · 관련 분석: /ops/known-gaps 의 Timshel fork drift 항목.

Scope: 본 PR 은 axe.2 의 2 patch 만 다룸. axe.3 의 organizations Owner-skip 제거 + cipher.permissions backport 는 별 PR 권장 (§7 참조).

1. Summary

Timshel/vaultwarden fork 가 dani-garcia/vaultwarden mainline 대비 2개 endpoint 가 outdated → bw CLI 2026.4+ / Bitwarden Chrome extension >= 2026.4 와 호환 깨짐. 본 PR 가 2 minimal patch 로 mainline 동등 shape 회복.

2. Motivation

2.1 Symptom

• bw CLI 2025.7.0 까지는 호환 정상.
• bw CLI 2026.4.x + Bitwarden Chrome ext 2026.4+ 에서 SSO user unlock 시도 시 다음 에러:
  • Master password unlock data was not found
  • Cannot read properties of null (reading 'toWrappedAccountCryptographicState')

2.2 Trigger

새 Bitwarden client (2026.4.x) 가 unlock flow 에서 server 측 응답 shape 의존성 강화 (mainline vaultwarden 의 새 spec). Timshel 은 옛 spec 유지 → 새 client 가 expect 하는 field 부재로 unlock 차단.

2.3 Affected

• Timshel fork 사용자 + 2026.4.x bw client 조합.
• SSO 인증 후 master password unlock 흐름.

2.4 Workaround (현재 운영)

• 클라이언트 측: npm install -g @bitwarden/[email protected] 으로 pin (임시).
• 서버 측 (영구): 본 PR 의 2 patch 적용 — AXE Labs 는 axe.2 release 로 production 운영 중.

3. Changes

3.1 Patch 0001 — /accounts/prelogin/password alias

File: src/api/identity.rs (또는 동등 router).

Change (개념):

// 기존
.route("/accounts/prelogin", post(prelogin))
 
// 추가
.route("/accounts/prelogin/password", post(prelogin))  // mainline alias

또는 동일 handler 가 두 path 모두 처리하도록 등록.

Rationale: dani-garcia/vaultwarden mainline 의 /accounts/prelogin/password endpoint 와 동일 response shape. bw 2026.4 client 가 본 path 호출 → 200 OK + shape (kdf, kdfIterations 등) 받아 unlock 진행.

3.2 Patch 0002 — /identity/connect/token AccountKeys/MasterPasswordUnlock

File: src/api/identity.rs (또는 connect_token handler).

Change (개념):

struct TokenResponse {
    // ... 기존 field
    AccountKeys: AccountKeysData,         // 신규
    MasterPasswordUnlock: MpUnlockData,   // 신규
}
 
struct AccountKeysData {
    publicKey: String,
    encryptedPrivateKey: String,
    // ... mainline 동등
}
 
struct MpUnlockData {
    kdf: KdfType,
    kdfIterations: i32,
    kdfMemory: Option<i32>,
    kdfParallelism: Option<i32>,
    salt: String,
    masterKeyWrappedUserKey: String,
    emailKdfIterations: Option<i32>,
    // ... mainline 동등
}

Rationale: mainline vaultwarden 의 /identity/connect/token response 와 동일 field set. 2026.4+ client 가 본 field 로 unlock flow 진행.

4. Testing

4.1 Manual verification (AXE Labs production, 2026-05-26)

Server 측 (axe.2 image deploy 후):

curl -X POST https://axe.axelabs.ai/vault/api/accounts/prelogin/password \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
# Expected: 200 OK + {kdf, kdfIterations, ...}

Client 측 (bw CLI 2026.4+):

bw config server https://axe.axelabs.ai/vault
bw login --sso
# Expected: SSO + MP flow 통과, unlock 성공

4.2 Real-world validation

• AXE Labs production 운영 (2026-05-26 부터): axe.2 image deploy 후 bw CLI 2026.4.x + Chrome ext 2026.4.x 모두 정상 unlock 검증.
• Real users: 4 명 (운영자 + 3 임직원) — 회귀 0 보고.

5. Compatibility

• Backward compat: 기존 /accounts/prelogin 그대로 유지 → 옛 client (2025.x 이하) 영향 0.
• Forward compat: mainline vaultwarden 의 shape 와 동등 → 미래 client update 와도 정합.
• Database migration: 없음 — 모두 response shape 변경만.

6. Code reference

AXE Labs 의 fork repo: https://github.com/axelabs-ai/vault 

• axe.2 release commit: TBD (운영자가 commit hash 채울 것)
• patches/0001_prelogin_password_alias.patch
• patches/0002_connect_token_account_keys_mp_unlock.patch

Mainline reference:

• dani-garcia/vaultwarden 의 동등 코드 위치 (PR 제출 시 commit/file 링크 첨부 권장).

7. Related (별 PR 권장)

axe.3 release 의 추가 2 patch — 본 PR scope 외:

• Patch 0003: organizations Owner-skip 3 site removal — post_organization_collections + post_bulk_access_collections + post_organization_collection_update 의 if member.access_all { continue; } 제거 → Owner 도 명시 users_collections row 생성.
• Patch 0004: cipher.rs::to_json User-sync branch 에 permissions: {response: null, delete: <bool-escape>, restore: <bool-escape>} 추가.

위 2 patch 는 organization permission model 의 mainline 정합 — 별 PR 로 분리 제출 권장 (review surface 분리 + 본 PR 의 compatibility-only 성격 유지).

8. Status

9. Submission channels

• Repo: https://github.com/Timshel/vaultwarden 
• PR title: Backport prelogin/password alias + connect/token AccountKeys/MasterPasswordUnlock from dani-garcia mainline (bw 2026.4+ compatibility)
• Label 권장: compatibility, mainline-backport

운영자가 검토 후 위 채널로 PR 제출. 회신 수령 시 본 페이지 §8 표를 갱신하고 /ops/backlog 의 B-vault-axe.2-patches-upstream-pr 를 ✅ 로 이동.