Understanding Safe States

SafekeeperLife safes move through different states during their lifecycle. Understanding these states helps you know what operations are available and why certain actions are restricted.

Table of Contents

• State Machine Overview
• The Five States
• State Transitions
• What You Can Do in Each State
• Why Restrictions Exist
• Common State Transition Scenarios
• Troubleshooting State Issues

State Machine Overview

A Safe’s state determines what operations you can perform. Think of states as phases in the Safe’s lifecycle:

1. Unlocked - Edit credentials freely
2. Locked - Credentials encrypted, ready to seal
3. Sealed - Keys distributed to Keyholders, waiting for reveal
4. Revealed - Keyholders unlocked the Safe, credentials visible
5. Removed - Safe deleted (terminal state)

State Diagram

stateDiagram-v2
    [*] --> Unlocked: Create Safe
    Unlocked --> Locked: Lock (encrypt credentials)
    Locked --> Unlocked: Unlock (enter password)
    Locked --> Sealed: Seal (distribute Keys)
    Sealed --> Revealed: Reveal (threshold Keys uploaded)
    Revealed --> Removed: Remove Safe
    Removed --> [*]

    note right of Unlocked
        Edit credentials
        Add/delete items
        Manage Keyholders
    end note

    note right of Locked
        Credentials encrypted
        Can't edit
        Ready to seal
    end note

    note right of Sealed
        Keys with Keyholders
        Waiting for trigger
        Can't edit or unlock
    end note

    note right of Revealed
        Credentials visible
        Keyholders have access
        Read-only
    end note

The Five States

Status: 🔓 Unlocked

Status: 🔒 Locked

Status: 🔐 Sealed
Trigger: [Inactivity / Attestation / Scheduled]
Keys Distributed: Yes

Status: ✅ Revealed
Keys Used: [K] out of [N]
Revealed At: [timestamp]

Status: 🗑️ Removed

State Transitions

Transition 1: Create → Unlocked

Trigger: Create a new Safe

Requirements:

• Choose a threshold (k)
• Set a master password

What Happens:

• Safe is created in unlocked state
• You can add credentials immediately

Transition 2: Unlocked → Locked

Trigger: Lock the Safe

Requirements:

• Enter your master password (confirmation)

What Happens:

• All credentials are encrypted using AES-256-GCM
• Encryption Key is derived from your password using PBKDF2
• Credentials are stored encrypted in the database
• Safe status changes to “locked”

Why You’d Do This:

• Finished adding/editing credentials
• Ready to seal and distribute Keys
• Want to encrypt credentials for security

Can You Undo? Yes, unlock with your password (see Transition 3).

Transition 3: Locked → Unlocked

Trigger: Unlock the Safe

Requirements:

• Enter your master password

What Happens:

• Encryption Key is re-derived from your password
• Credentials are temporarily decrypted (in memory)
• You can view and edit credentials
• Safe status changes to “unlocked”

Why You’d Do This:

• Need to edit credentials (update password, add 2FA codes)
• Need to add/delete credentials
• Need to update Keyholder list

Can You Do This After Sealing? No. Once sealed, you cannot unlock with password alone.

Transition 4: Locked → Sealed

Trigger: Seal the Safe

Requirements:

• Safe must be locked
• Must have designated Keyholders (at least K Keyholders)

What Happens:

• Encryption Key is split into N shares (Shamir’s Secret Sharing)
• Each Keyholder receives a Key file via email
• If emergency triggers are enabled, shares are pre-encrypted for trigger-based sealing
• Safe status changes to “sealed”
• You can no longer unlock with password alone

Why You’d Do This:

• Finished setting up the Safe
• Ready to distribute Keys to Keyholders
• Want Keyholders to be able to reveal in the future

Can You Undo? No. Sealing is irreversible. You must coordinate with Keyholders to reveal.

Transition 5: Sealed → Revealed

Trigger: Threshold Keys uploaded by Keyholders

Requirements:

• A trigger condition must be met (inactivity, attestation, or scheduled)
• K or more Keyholders upload their Key files
• Key shares are cryptographically valid

What Happens:

• K shared Keys are combined to reconstruct the encryption Key
• Credentials are decrypted
• Safe status changes to “revealed”
• Credentials are visible to all Keyholders who participated

Why This Happens:

• Emergency condition occurred (safekeeper inactive, deceased, scheduled date reached)
• Keyholders coordinated to reveal the Safe

Can You Undo? No. Once revealed, you cannot re-seal. You can only remove the Safe.

Transition 6: Revealed → Removed

Trigger: Remove the Safe

Requirements:

• Safe must be in revealed state
• Click “Remove Safe” and confirm

What Happens:

• All credentials permanently deleted
• All shared Keys deleted
• All metadata deleted
• Safe status changes to “removed” (terminal)

Why You’d Do This:

• Finished accessing credentials
• Keyholders have completed their tasks
• No longer need the Safe

Can You Undo? No. Removal is permanent.

What You Can Do in Each State

Notes:

• *In revealed state, only Keyholders who uploaded Keys can view
• **In locked state, you can manage Keyholders, but if emergency triggers are enabled with pre-encrypted shares, you cannot change the number of Keyholders or threshold (structural constraints)
• *Keys can only be uploaded after a trigger condition is met

Why Restrictions Exist

Why Can’t I Edit After Locking?

Reason: Credentials are encrypted. To edit, you need to decrypt them first (unlock).

Analogy: A locked physical Safe doesn’t let you add/remove items without opening it first.

Solution: Unlock the Safe, edit, lock again.

Why Can’t I Unlock After Sealing?

Reason: The encryption Key has been split into shares. Your password alone cannot reconstruct the Key.

Cryptographic Explanation:

1. When you lock: Password → PBKDF2 → Encryption Key → Encrypt Credentials
2. When you seal: Encryption Key → Shamir Split → K-of-N Shares → Distribute to Keyholders
3. You no longer have the full encryption Key (only Keyholders have shares)

Analogy: You’ve split a physical Key into pieces and given them to Keyholders. You can’t unlock the Safe without reassembling the Key pieces.

Solution: Coordinate with Keyholders to reveal (requires K Keyholders to upload Keys).

Why Can’t I Change Keyholders After Locking (If Triggers Enabled)?

Reason: If you’ve enabled emergency triggers (inactivity, attestation, scheduled), the shared Keys are pre-encrypted for trigger-based sealing. Changing the number of Keyholders or threshold would invalidate these pre-encrypted shares.

Technical Explanation:

• Trigger monitors need to seal the Safe without your password
• Key shares are pre-encrypted with trigger-specific Keys during lock
• Changing Keyholder count or threshold requires regenerating shares
• Regenerating shares requires the encryption Key (which is only available during lock)

What You CAN Change:

• Keyholder names (cosmetic)
• Keyholder emails (if before sealing)

What You CANNOT Change:

• Number of Keyholders
• Threshold value

Solution: If you need to change threshold or Keyholder count:

1. Disable emergency triggers
2. Unlock, edit Keyholder list, lock again (without triggers)
3. OR: Create a new Safe with desired threshold/Keyholder configuration

Why Can’t I Re-Seal After Revealing?

Reason: The Safe’s purpose has been fulfilled. Credentials are accessible, and the Safe is meant to be removed after use.

Design Philosophy: SafekeeperLife is designed for one-time reveal. Once Keyholders have accessed credentials, the Safe should be cleaned up.

What You CAN Do:

• View credentials (read-only)
• Export credentials (to store elsewhere)
• Remove the Safe (cleanup)

What You CANNOT Do:

• Edit credentials
• Re-seal and redistribute Keys

Solution: If you need to store credentials again, create a new Safe.

Common State Transition Scenarios

Scenario 1: Normal Setup Workflow

[Create Safe]
    ↓
[Unlocked] - Add credentials, designate Keyholders
    ↓
[Lock] - Enter password, encrypt credentials
    ↓
[Sealed] - Distribute Keys to Keyholders
    ↓
[Wait for Trigger] - Inactivity / Attestation / Scheduled
    ↓
[Revealed] - Keyholders upload Keys
    ↓
[Removed] - Cleanup after accessing credentials

Scenario 2: Edit After Locking (Before Sealing)

[Locked] - Realized I forgot a credential
    ↓
[Unlock] - Enter password
    ↓
[Unlocked] - Add the forgotten credential
    ↓
[Lock] - Re-encrypt with updated credentials
    ↓
[Sealed] - Distribute Keys (includes new credential)

Scenario 3: Edit After Sealing (Requires Re-Seal)

[Sealed] - Password changed, need to update Safe
    ↓
[Cannot Unlock] - Sealed safes can't be unlocked with password
    ↓
[Option 1: Reveal]
    - Coordinate with Keyholders
    - Upload K Keys to reveal
    - View old credentials
    - Remove Safe
    - Create new Safe with updated credentials

[Option 2: Create New Safe]
    - Create new Safe with current credentials
    - Seal and distribute new Keys
    - Keep old Safe sealed (for old credentials)

Recommendation: If credentials change frequently, keep the Safe locked (not sealed) until you’re confident credentials are stable.

Scenario 4: Testing the Reveal Process

[Create Test Safe]
    ↓
[Unlocked] - Add dummy credentials
    ↓
[Lock] - Encrypt test data
    ↓
[Sealed] - Trigger fires, Keys distributed to Keyholders
    ↓
[Revealed] - Keyholders upload Keys (practice)
    ↓
[Verify Credentials Visible] - Confirm reveal works
    ↓
[Removed] - Delete test Safe

Best Practice: Always test the reveal process with a dummy Safe before relying on it for real credentials.

Troubleshooting State Issues

Problem: Can’t Find “Lock” Button

Symptom: Safe is unlocked, but no lock button appears.

Possible Causes:

• No credentials added yet
• JavaScript not loaded
• Browser issue

Solution:

1. Add at least one credential
2. Refresh the page
3. Try a different browser

Problem: Can’t Edit Credentials

Symptom: Edit button is grayed out or missing.

Cause: Safe is not in unlocked state.

Solution:

• If locked: Unlock the Safe (enter password)
• If sealed: Cannot edit (must reveal or create new Safe)
• If revealed: Cannot edit (read-only state)

Problem: Forgot Password, Safe is Locked

Symptom: Safe is locked, but you forgot the master password.

Cause: Master password not stored or remembered.

Solution: There is no solution. Credentials are permanently unrecoverable. This is by design for security.

Prevention:

• Write down master password and store securely
• Use a memorable passphrase
• Store password in a different password manager

Problem: Safe Stuck in Sealed State

Symptom: Safe is sealed, but you want to edit without revealing.

Cause: Sealing is irreversible.

Solutions:

1. Reveal the Safe (requires Keyholders)

   • Coordinate with Keyholders
   • Upload K Keys
   • View credentials
   • Remove Safe
   • Create new Safe with updated data

2. Create a new Safe (if old credentials still valid)

   • Leave old Safe sealed (for old credentials)
   • Create new Safe with current credentials
   • Seal and distribute new Keys

Recommendation: Avoid sealing until you’re confident credentials are stable.

Problem: Revealed Safe Won’t Let Me Edit

Symptom: Safe is revealed, credentials visible, but can’t edit.

Cause: Revealed state is read-only.

Solution: You cannot edit revealed safes. You must:

1. Export/view credentials
2. Remove the Safe
3. Create a new Safe with updated credentials

Related Documentation

• Getting Started Guide - Your first Safe walkthrough
• User Guide: Credential Management - CRUD operations and workflows
• Keyholder Guide: Reveal Process - What Keyholders do
• Emergency Triggers User Guide - Automatic trigger configuration
• Developer Guide: State Machine - FSM internals (for developers)

Questions? See the General FAQ or Getting Started Guide.