feat: vault recovery via mnemonic (plan 35); bump __version__ to 0.6.0

Author: vardhin

backend/raspy/__init__.py

@@ -1,3 +1,3 @@
 """Raspy — modular FastAPI control plane for a personal Raspberry Pi."""
 
-__version__ = "0.5.3"
+__version__ = "0.6.0"

backend/raspy/core/auth/router.py

@@ -18,11 +18,13 @@
     ACCESS_COOKIE,
     CSRF_COOKIE,
     REFRESH_COOKIE,
+    Principal,
     check_csrf,
     client_ip,
     get_auth,
     refresh_token_from,
     require_admin,
+    require_auth,
 )
 from .service import AuthError, AuthService, LoginResult
 
@@ -64,6 +66,24 @@ class UpdateChildBody(BaseModel):
     allowed_apps: list[str] = Field(default_factory=list)
 
 
+class SetRecoveryBody(BaseModel):
+    """Opaque recovery wraps the browser computed (plan/35). All values are b64
+    ciphertext / a public salt; the server stores them verbatim."""
+    recovery_salt: str = Field(min_length=1, max_length=128)
+    wrap_pw: str = Field(min_length=1, max_length=512)
+    wrap_pw_nonce: str = Field(min_length=1, max_length=128)
+    wrap_mn: str = Field(min_length=1, max_length=512)
+    wrap_mn_nonce: str = Field(min_length=1, max_length=128)
+
+
+class RecoverBody(BaseModel):
+    """Break-glass password reset proven by the mnemonic (client-side). The server
+    only takes the new auth_key (+ optional PIN); the wraps/DEK are untouched."""
+    username: str = Field(min_length=1, max_length=128)
+    new_auth_key: str = Field(min_length=1, max_length=512)
+    new_pin: str | None = Field(default=None, min_length=1, max_length=256)
+
+
 def _settings(request: Request) -> Settings:
     return request.app.state.settings
 
@@ -131,6 +151,64 @@ async def kdf_params(request: Request, username: str, svc: AuthService = Depends
     return salts
 
 
+@router.get("/recovery/{username}")
+async def recovery_material(
+    request: Request, username: str, svc: AuthService = Depends(get_auth)
+):
+    """Public: the opaque recovery wraps + salt the client needs to recover the
+    DEK from a mnemonic (or to detect whether migration has happened). Like
+    /kdf, the values are non-secret. A missing account returns the same shape with
+    nulls + dek_migrated:false, so it doesn't reveal whether the user exists."""
+    material = await svc.recovery_material(username)
+    if material is None:
+        material = {
+            "recovery_salt": None,
+            "wrap_pw": None, "wrap_pw_nonce": None,
+            "wrap_mn": None, "wrap_mn_nonce": None,
+            "dek_migrated": False,
+        }
+    return material
+
+
+@router.put("/recovery", status_code=204)
+async def set_recovery(
+    request: Request, body: SetRecoveryBody,
+    svc: AuthService = Depends(get_auth),
+    principal: Principal = Depends(require_auth),
+):
+    """Authed: the client stores its recovery wraps for its OWN account (migration
+    or a wrap rotation). Scoped to the principal — a user can only write their own
+    envelope."""
+    check_csrf(request, _settings(request).auth)
+    try:
+        await svc.set_recovery(
+            principal.username,
+            recovery_salt=body.recovery_salt,
+            wrap_pw=body.wrap_pw, wrap_pw_nonce=body.wrap_pw_nonce,
+            wrap_mn=body.wrap_mn, wrap_mn_nonce=body.wrap_mn_nonce,
+        )
+    except AuthError as exc:
+        raise HTTPException(400, str(exc))
+
+
+@router.post("/recover", status_code=204)
+async def recover(
+    request: Request, response: Response, body: RecoverBody,
+    svc: AuthService = Depends(get_auth),
+):
+    """Public, rate-limited: break-glass password reset proven by the mnemonic.
+    The client has already unwrapped the DEK from wrap_mn locally; here we only
+    reset the login hash, then the client re-PUTs wrap_pw under the new password.
+    Sessions are revoked so the user signs in fresh."""
+    try:
+        await svc.recover_password(
+            body.username, body.new_auth_key, body.new_pin, ip=_ip(request)
+        )
+    except AuthError as exc:
+        raise _auth_error(exc)
+    _clear_session_cookies(response)
+
+
 @router.post("/login")
 async def login(
     request: Request, response: Response, body: LoginBody,

backend/raspy/core/auth/service.py

@@ -107,7 +107,19 @@ async def init(self) -> None:
                 must_reset  INTEGER NOT NULL DEFAULT 0,
                 -- JSON list of attachment ids this account may see; NULL = all
                 -- (admin). Children get an explicit allow-list.
-                allowed_apps TEXT
+                allowed_apps TEXT,
+                -- Recovery envelope (plan/35). The vault root is a random DEK;
+                -- it is wrapped under the password-KEK and (optionally) a
+                -- mnemonic-KEK, both client-side. The server stores only opaque
+                -- wraps — it never sees the DEK, password, or mnemonic. All NULL
+                -- + dek_migrated=0 means a legacy account whose DEK == the
+                -- password-derived master_key (migrated on next browser unlock).
+                recovery_salt TEXT,   -- salt for the mnemonic KEK (16B, b64)
+                wrap_pw       TEXT,   -- secretbox(DEK, nonce_pw, KEK_pw),  b64
+                wrap_pw_nonce TEXT,
+                wrap_mn       TEXT,   -- secretbox(DEK, nonce_mn, KEK_mn),  b64
+                wrap_mn_nonce TEXT,
+                dek_migrated  INTEGER NOT NULL DEFAULT 0
             )
             """
         )
@@ -174,6 +186,15 @@ async def _migrate_account_columns(self) -> None:
             "role": "TEXT NOT NULL DEFAULT 'admin'",
             "must_reset": "INTEGER NOT NULL DEFAULT 0",
             "allowed_apps": "TEXT",
+            # Recovery envelope (plan/35) — additive, all nullable. Existing rows
+            # get dek_migrated=0 ⇒ treated as legacy (DEK == master_key) until the
+            # client migrates on next password unlock.
+            "recovery_salt": "TEXT",
+            "wrap_pw": "TEXT",
+            "wrap_pw_nonce": "TEXT",
+            "wrap_mn": "TEXT",
+            "wrap_mn_nonce": "TEXT",
+            "dek_migrated": "INTEGER NOT NULL DEFAULT 0",
         }
         for col, decl in adds.items():
             if col not in have:
@@ -228,6 +249,81 @@ def _salt(tag: str) -> str:
             "argon_parallelism": self._cfg.argon_parallelism,
         }
 
+    # --- recovery envelope (plan/35) -----------------------------------------
+
+    async def recovery_material(self, username: str) -> dict[str, Any] | None:
+        """The opaque recovery wraps + salt the client needs to recover the DEK
+        from a mnemonic (and to know whether the account is migrated yet). Returns
+        None for a missing account. All values are opaque/non-secret ciphertext or
+        public salts — like kdf_salts, this is safe to serve pre-auth."""
+        account = await self._get_account(username)
+        if account is None:
+            return None
+        return {
+            "recovery_salt": account.get("recovery_salt"),
+            "wrap_pw": account.get("wrap_pw"),
+            "wrap_pw_nonce": account.get("wrap_pw_nonce"),
+            "wrap_mn": account.get("wrap_mn"),
+            "wrap_mn_nonce": account.get("wrap_mn_nonce"),
+            "dek_migrated": bool(account.get("dek_migrated")),
+        }
+
+    async def set_recovery(
+        self, username: str, *,
+        recovery_salt: str,
+        wrap_pw: str, wrap_pw_nonce: str,
+        wrap_mn: str, wrap_mn_nonce: str,
+    ) -> None:
+        """Persist the recovery envelope wraps for an account and flag it migrated.
+
+        Written by the browser after it mints the DEK + mnemonic (first migration)
+        or rotates a wrap (password change / mnemonic re-issue). The server stores
+        only opaque blobs; it never learns the DEK, password, or mnemonic."""
+        if await self._get_account(username) is None:
+            raise AuthError(f"no such account {username!r}")
+        await self._db.execute(
+            f"UPDATE {_T_ACCOUNT} SET "
+            f"recovery_salt = ?, wrap_pw = ?, wrap_pw_nonce = ?, "
+            f"wrap_mn = ?, wrap_mn_nonce = ?, dek_migrated = 1 "
+            f"WHERE username = ?",
+            (recovery_salt, wrap_pw, wrap_pw_nonce, wrap_mn, wrap_mn_nonce, username),
+        )
+
+    async def recover_password(
+        self, username: str, new_auth_key: str, new_pin: str | None, *, ip: str | None
+    ) -> None:
+        """Break-glass reset: set a new password (+ optional PIN) without touching
+        the recovery wraps or the DEK. The caller has already proven possession of
+        the mnemonic *client-side* by unwrapping wrap_mn → DEK; the server only
+        resets the login hash here. The client then re-PUTs a fresh wrap_pw under
+        the new password-KEK (set_recovery), so the vault stays intact.
+
+        Rate-limited on the account + IP like a login, so this can't be used to
+        brute the username space. Revokes existing sessions."""
+        await self._check_locked("ip", ip or "?")
+        await self._check_locked("account", username)
+        account = await self._get_account(username)
+        if account is None or not bool(account.get("dek_migrated")):
+            # No migrated account ⇒ no mnemonic exists to recover with. Record a
+            # failure (constant-ish) so probing is rate-limited, then refuse.
+            await self._record_failure("ip", ip or "?")
+            await self._record_failure("account", username)
+            await self._audit("recover", False, ip, username)
+            raise AuthError("recovery unavailable")
+        updates = "pw_hash = ?"
+        params: list[Any] = [self._ph.hash(new_auth_key)]
+        if new_pin:
+            updates += ", pin_hash = ?"
+            params.append(self._ph.hash(new_pin))
+        params.append(username)
+        await self._db.execute(
+            f"UPDATE {_T_ACCOUNT} SET {updates} WHERE username = ?", tuple(params)
+        )
+        await self._reset_attempts("ip", ip or "?")
+        await self._reset_attempts("account", username)
+        await self.revoke_all(username)
+        await self._audit("recover", True, ip, username)
+
     async def create_account(
         self, username: str, auth_key: str, pin: str | None,
         auth_salt: str, master_salt: str,

backend/tests/test_auth.py

@@ -251,3 +251,92 @@ async def test_child_setup_requires_temp_pin_and_blocks_unallowed_apps(setup):
     assert "vault" not in app_ids
     assert (await client.get("/api/att/notes/notes")).status_code == 200
     assert (await client.get("/api/att/vault/manifest")).status_code == 403
+
+
+# --- recovery envelope (plan/35) ---------------------------------------------
+
+_WRAPS = {
+    "recovery_salt": "cmVjb3Zlcnktc2FsdC0xNg",
+    "wrap_pw": "d3JhcF9wdw",
+    "wrap_pw_nonce": "d3JhcF9wd19ub25jZQ",
+    "wrap_mn": "d3JhcF9tbg",
+    "wrap_mn_nonce": "d3JhcF9tbl9ub25jZQ",
+}
+
+
+async def test_recovery_material_legacy_unmigrated(setup):
+    client, _ = setup
+    r = await client.get(f"/api/auth/recovery/{USERNAME}")
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["dek_migrated"] is False
+    assert body["wrap_pw"] is None and body["wrap_mn"] is None
+
+
+async def test_recovery_material_missing_user_is_decoy(setup):
+    client, _ = setup
+    # A non-existent user returns the same null shape, not a 404 (no existence leak).
+    r = await client.get("/api/auth/recovery/ghost")
+    assert r.status_code == 200
+    assert r.json()["dek_migrated"] is False
+
+
+async def test_put_recovery_requires_auth(setup):
+    client, _ = setup
+    client.cookies.clear()
+    r = await client.put("/api/auth/recovery", json=_WRAPS)
+    assert r.status_code == 401
+
+
+async def test_put_recovery_migrates_and_persists(setup):
+    client, salt = setup
+    csrf = (await _login(client, salt)).json()["csrf_token"]
+    r = await client.put(
+        "/api/auth/recovery", json=_WRAPS, headers={"X-CSRF-Token": csrf}
+    )
+    assert r.status_code == 204, r.text
+    mat = (await client.get(f"/api/auth/recovery/{USERNAME}")).json()
+    assert mat["dek_migrated"] is True
+    assert mat["wrap_pw"] == _WRAPS["wrap_pw"]
+    assert mat["wrap_mn"] == _WRAPS["wrap_mn"]
+    assert mat["recovery_salt"] == _WRAPS["recovery_salt"]
+
+
+async def test_recover_refused_before_migration(setup):
+    client, _ = setup
+    client.cookies.clear()
+    r = await client.post(
+        "/api/auth/recover",
+        json={"username": USERNAME, "new_auth_key": "brand-new-key"},
+    )
+    # No mnemonic exists yet → refused (401), and the wraps stay absent.
+    assert r.status_code == 401
+
+
+async def test_recover_after_migration_resets_and_revokes(setup):
+    client, salt = setup
+    # Migrate first (authed PUT), then recover from a clean (pre-auth) client.
+    csrf = (await _login(client, salt)).json()["csrf_token"]
+    assert (await client.put(
+        "/api/auth/recovery", json=_WRAPS, headers={"X-CSRF-Token": csrf}
+    )).status_code == 204
+    client.cookies.clear()
+
+    new_key = "recovered-auth-key"
+    r = await client.post(
+        "/api/auth/recover",
+        json={"username": USERNAME, "new_auth_key": new_key, "new_pin": "424242"},
+    )
+    assert r.status_code == 204, r.text
+
+    # The wraps/DEK are untouched by recover (only the login hash changed).
+    mat = (await client.get(f"/api/auth/recovery/{USERNAME}")).json()
+    assert mat["wrap_pw"] == _WRAPS["wrap_pw"] and mat["wrap_mn"] == _WRAPS["wrap_mn"]
+
+    # The old password no longer works; the new one does.
+    assert (await client.post(
+        "/api/auth/login", json={"username": USERNAME, "auth_key": AUTH_KEY}
+    )).status_code == 401
+    assert (await client.post(
+        "/api/auth/login", json={"username": USERNAME, "auth_key": new_key}
+    )).status_code == 200

frontend/bun.lock

@@ -25,6 +25,7 @@
 	},
 	"dependencies": {
 		"@chenglou/pretext": "0.0.8",
+		"@scure/bip39": "^2.2.0",
 		"@xterm/addon-fit": "^0.11.0",
 		"@xterm/xterm": "^6.0.0",
 		"libsodium-wrappers": "^0.8.4",