> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.krkn.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Emergency Access & Recovery

> Dead-man switch emergency sharing, recovery keys, and account recovery

# Emergency Access & Recovery

Argon provides two distinct safety nets: **emergency access** (a dead-man switch that grants a contact access to your vaults after prolonged inactivity) and **recovery keys** (a personal escape hatch for regaining access when you lose your master password).

***

## How It Works

```text theme={null}
Day 0:   User configures emergency access
         → contact email, countdown (7/14/30/60/90 days), vault selection
         → Server creates dormant escrow account
         → Client wraps vault keys to escrow account's X25519 public key

Day 1-N: User logs in normally
         → LastActivity timestamp refreshes on every login
         → Nothing happens

Day N+1: User stops logging in
         → Background checker runs hourly
         → Detects: time.Since(LastActivity) > CountdownDays
         → Emergency is triggered

Trigger: Server activates escrow account
         → Creates invite for the emergency contact
         → Sends invite via email (if SMTP configured) or admin delivers manually
         → Contact registers using the invite
         → Escrow envelopes grant read access to the user's designated vaults
```

***

## Escrow Key Wrapping

The security model ensures the server never has access to vault contents, even during emergency activation.

### Setup (Client-Side)

```text theme={null}
1. Server creates escrow account with its own X25519 key pair
2. Client fetches escrow account's public key
3. For each designated vault:
   a. Client retrieves its own copy of the vault DEK
   b. Client wraps DEK to escrow's X25519 public key:
      shared_secret = X25519(user_private, escrow_public)
      wrap_key = HKDF-SHA256(shared_secret, "escrow-envelope")
      wrapped_dek = XChaCha20-Poly1305(wrap_key, vault_dek)
   c. Client uploads: EscrowEnvelope { user_id, vault_id, wrapped_key, nonce }
```

### Activation (Server-Side)

```text theme={null}
1. Server marks emergency as triggered
2. Server creates an invite tied to the contact's email
3. Contact registers using the invite code
4. Contact's account receives the escrow envelopes
5. Contact's client unwraps DEKs using the escrow private key
6. Contact can now decrypt the designated vaults
```

The server orchestrates the handoff but never possesses the plaintext vault keys. The escrow private key is encrypted to the contact's credentials during the invite acceptance flow.

***

## Configuration

| Setting             | Options                | Description                                             |
| ------------------- | ---------------------- | ------------------------------------------------------- |
| **Contact email**   | Any email address      | The person who gains access when the emergency triggers |
| **Countdown days**  | 7, 14, 30, 60, 90      | Days of inactivity before triggering                    |
| **Vault selection** | Specific vaults or all | Which vaults the contact can access                     |

### Modify or Disable

* **Modify** — The user can change the contact, countdown, or vault selection at any time. Changing the vault selection requires re-wrapping escrow envelopes.
* **Disable** — Removes the emergency config, deletes the escrow account and all escrow envelopes.
* **Manual trigger** — Admins can manually trigger emergency access for testing or urgent situations.

***

## Email Delivery

Emergency invite emails are sent via the server's SMTP configuration:

* SMTP must be configured via `AdminService.SetSMTPConfig` (admin-only).
* SMTP must be confirmed via `AdminService.TestSMTPConnection`.
* If SMTP is not configured (airgapped environment), the admin must manually deliver the invite code to the emergency contact.

The `Confirmed` flag resets whenever any SMTP field is changed, forcing re-verification before emails can be sent.

***

## Dormant Escrow Accounts

The escrow account created during emergency setup is a **dormant user** — it has key pairs but no auth verifier, meaning it cannot be logged into directly. Its username follows the pattern `__escrow_{userID}_{random}` and it exists solely to hold the X25519 public key that vault DEKs are wrapped to.

When the emergency triggers, the server updates the escrow account's identity to match the contact's email and issues an invite. The contact registers using the invite, inherits the escrow envelopes, and gains access to the designated vaults.

***

## Recovery Keys

Separate from emergency access, every Argon user has a **recovery key envelope** — a personal backup mechanism for regaining access when the master password is lost.

### How Recovery Keys Work

```text theme={null}
Registration:
  1. Client generates recovery_key (256-bit random)
  2. Client encrypts user's private keys with recovery_key
  3. Encrypted blob stored as RecoveryKeyEnvelope on the UserRecord
  4. Plaintext recovery key shown to the user ONCE (they must write it down)

Recovery:
  1. User provides recovery_key (the string they wrote down)
  2. Client decrypts RecoveryKeyEnvelope → recovers private keys
  3. User sets a new master password
  4. Client re-encrypts private keys with new password-derived encryption_key
  5. Client updates auth_verifier on the server
  6. Recovery key envelope is regenerated (new recovery key issued)
```

### Key Properties

* The recovery key is shown exactly **once** during registration. Argon does not store it.
* The recovery key envelope is stored on the server as an opaque encrypted blob — the server cannot decrypt it.
* Using a recovery key invalidates the old one and generates a new one (preventing reuse after compromise).
* Recovery keys are independent of emergency access — they let the **same user** recover their own account, not grant access to someone else.

### Recovery Key vs Emergency Access

|                 | Recovery Key                           | Emergency Access                               |
| --------------- | -------------------------------------- | ---------------------------------------------- |
| **Who uses it** | The account owner                      | A designated contact                           |
| **When**        | Master password forgotten              | Owner inactive for N days                      |
| **Trigger**     | Manual (user provides key)             | Automatic (dead-man switch)                    |
| **Result**      | User regains access, sets new password | Contact gains read access to designated vaults |
| **Key storage** | User's own backup (paper, safe)        | Escrow envelopes on server                     |

***

## Audit Trail

| Event                           | Logged                                      |
| ------------------------------- | ------------------------------------------- |
| Emergency access configured     | Contact email, countdown, vault IDs         |
| Emergency access modified       | Changed fields                              |
| Emergency access disabled       | User ID                                     |
| Emergency triggered (automatic) | User ID, contact email, inactivity duration |
| Emergency triggered (manual)    | Triggering admin, target user               |
| Emergency invite accepted       | Contact registration                        |
| Recovery key used               | User ID, IP address                         |
| Password changed via recovery   | User ID                                     |