SYSTEM/docs/prd/epic-3-the-vault-social-recovery.md

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.

---