# 8. Epic 3: The "Vault" & Social Recovery

**Epic Goal:** To mitigate the primary risk of a decentralized identity system by introducing the optional "Vault" — a user-friendly, server-side storage for a Citizen's private key, secured by a traditional login/password. This epic will also implement the social recovery mechanism, allowing Citizens to regain access to their Vault-stored key with the help of their peers, thus adding a critical layer of safety and usability.

## Story 3.1: The "Vault" Opt-In

**As a** new or existing "Citizen", **I want** the option to create a "Vault" account (login/password) and store an encrypted copy of my private key on the server, **so that** I have a backup and a way to use the SYSTEM if I don't have my primary key file with me.

**Acceptance Criteria:**
1.  During the onboarding process (Story 2.2), after the private key is presented to the user, a new step must offer to create a "Vault" account.
2.  The user must provide a password, which will be used to encrypt their private key on the client-side before it's sent to the server for storage. The server must only store the encrypted key and a salted hash of the password.
3.  The UI must clearly explain that this is an **optional** convenience feature and that the most secure method is managing the key oneself.
4.  A logged-in "Citizen" who did not opt-in during onboarding must have an option in their profile to create a "Vault" account later.

## Story 3.2: Session Authentication via The "Vault"

**As a** "Citizen" with a "Vault" account, **I want** to be able to log into a new session using my login and password, **so that** the server can sign transactions on my behalf without me needing to provide my private key file.

**Acceptance Criteria:**
1.  The main login screen must have a toggle or separate form for "Login with Vault" (username/password).
2.  Upon successful login, the server must decrypt the user's private key using their password and hold it securely for the duration of the server-side session.
3.  When the user performs a signable action, the request is sent to the server, which then signs the transaction with the session-stored private key before committing it to "The Main Ledger".
4.  This flow must be distinct from the default client-side signing, where the server only receives an already-signed transaction.

## Story 3.3: Social Recovery for The "Vault"

**As a** "Citizen" with a "Vault" account who has forgotten their password, **I want** to initiate a recovery process that other "Citizens" can approve, **so that** I can regain access to my encrypted private key.

**Acceptance Criteria:**
1.  From the "Login with Vault" screen, there must be a "Forgot Password" link.
2.  The user must identify themselves (e.g., by their name/public key) to initiate a recovery request. A `RECOVERY_REQUESTED` transaction is logged.
3.  Other "Citizens" must see a notification about the pending recovery request on their dashboard.
4.  The request UI must show who is requesting recovery and require a quorum of other "Citizens" to approve it by signing a `RECOVERY_APPROVED` transaction. (Quorum rule: 1 approval if <=4 members; 2 approvals if >=5 members).
5.  Once the quorum is met, the server grants a temporary token, allowing the original user to reset their "Vault" password and re-encrypt their stored private key.

---