How It Works

This page explains the complete lifecycle of a digital will in Burning Ash Protocol, from creation to the eventual transfer to survivors.

Overview

The BAP system operates in three main phases:

1. Will Creation — Host sets up their will, documents, and survivors
2. Active Monitoring — Periodic liveness checks confirm the host is alive
3. Will Transfer — After confirmed death, survivors access the documents

Phase 1: Will Creation

Step 1: Account Setup

The host creates an account with:

• Email and password (hashed with Argon2)
• Display name
• Email verification

Step 2: Connector Configuration

The host configures one or more connectors — communication channels for notifications and OTPs:

• Email (any SMTP provider)
• SMS (Twilio)
• WhatsApp (Meta Cloud API)
• Telegram (Bot API)

Each connector requires specific credentials that are encrypted before storage.

Step 3: Storage Configuration

The host connects at least one storage backend where encrypted documents will be stored:

• Google Drive (OAuth 2.0)
• Dropbox (OAuth 2.0)
• AWS S3
• FTP/SFTP

Step 4: Survivor Registration

The host adds survivors with:

• Name and relationship
• At least one contact method (email, phone, WhatsApp, or Telegram)
• A personal message to display when they access the will

The host sets a threshold (K-of-N) — for example, 2-of-3 means any 2 survivors can access the will.

Step 5: Document Upload

The host uploads their important documents:

• Supported formats: PDF, DOCX, TXT, images (JPEG, PNG)
• Maximum: 50MB per file, 500MB total

Immediate encryption: Each file is encrypted with AES-256-GCM before upload. The server never stores plaintext documents.

Step 6: Sealing the Will

When the host seals their will:

1. A Data Encryption Key (DEK) is generated (256-bit)
2. The DEK encrypts all documents
3. The DEK is encrypted with the master key (envelope encryption)
4. The encrypted DEK is split into shares using Shamir's Secret Sharing (SSS)
5. Each survivor receives one share, encrypted with their personal key
6. The encrypted documents are uploaded to storage

The will is now active — the system begins liveness monitoring.

Phase 2: Active Monitoring

Liveness Checks

The system periodically checks if the host is alive using three configurable parameters:

Check Cycle

1. Scheduled check — System sends notification via the host's preferred connector
2. Response — Host window has HCRT hours to respond
3. If host responds — Check marked as confirmed, next check scheduled for HCIT
4. If host doesn't respond — Increment retry counter
5. Retry attempts — Send another notification (up to HCRAC times)
6. Activation — After HCRAC failures, mark host as "presumed dead"

Time to Activation

The total time from a missed check to will activation:

Time to Activation = HCRT × HCRAC

Example: 48 hours × 3 attempts = 144 hours (6 days)

With HCIT (30 days), the worst case is:

• 30 days until first missed check
• Plus 6 days of escalation
• Total: ~36 days from last response to activation

Survivor-Initiated Transfer

Survivors can also initiate the transfer process manually if they believe the host has died:

1. Survivor accesses the portal
2. Selects their name
3. OTP is sent to verify identity
4. Transfer is initiated
5. Host is notified immediately
6. Host can cancel within HCRT if still alive

Phase 3: Will Transfer

Step 1: Transfer Initiation

When the will transfer begins:

• All survivors are notified via their configured connectors
• Host is notified and can cancel within HCRT
• Transfer status changes to "initiated"

Step 2: Survivor Authentication

Each survivor must verify their identity:

1. Access the Survivor Portal
2. Select their name from the list
3. Receive 6-digit OTP via their primary connector
4. Enter OTP within 10 minutes (3 attempts max)
5. Or use a backup code if OTP unavailable

Progress tracking: The portal shows how many survivors have authenticated and the threshold progress.

Step 3: Share Combination

When K survivors have authenticated:

1. The system collects their SSS shares from server memory
2. Lagrange interpolation reconstructs the original DEK
3. The DEK decrypts the document encryption key
4. Documents are decrypted

Step 4: Document Access

Authenticated survivors can:

• View their personal message from the host
• Download decrypted documents
• Verify document integrity (SHA-256 hash check)

The access window is configurable (default: 7 days).

Key Security Properties

Encryption

• AES-256-GCM for document encryption
• Unique nonces per file (non-correlatable ciphertexts)
• Envelope encryption — DEK encrypted by master key
• No plaintext ever stored externally

Shamir's Secret Sharing

• K-of-N threshold — No single survivor can access alone
• Share encryption — Each share is encrypted for a specific survivor
• Server memory only — Shares are held in server memory during transfer, never persisted

Access Control

• OTP verification — Time-limited, rate-limited
• Backup codes — Single-use, physically distributed
• Audit logging — Every action is logged

Failure Scenarios

Insufficient Survivors

If fewer than K survivors authenticate within 30 days:

• Transfer status becomes "stalled"
• Weekly reminders are sent
• After 90 days, transfer is marked "failed"

Document Tampering

If SHA-256 hashes don't match during decryption:

• All survivors are alerted
• Access is still provided (with warning)
• Incident is logged

Storage Disconnection

If storage becomes unavailable during transfer:

• Cached presigned URLs are used if available
• Host is notified to reconnect
• Transfer may be delayed

Summary Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     WILL CREATION                                │
├─────────────────────────────────────────────────────────────────┤
│  Host → Account → Connectors → Storage → Survivors → Upload → Seal│
│                                          ↓                      │
│                              DEK generated + split via SSS       │
│                                          ↓                      │
│                              Will ACTIVE                         │
└─────────────────────────────────────────────────────────────────┘
                                            ↓
┌─────────────────────────────────────────────────────────────────┐
│                    ACTIVE MONITORING                            │
├─────────────────────────────────────────────────────────────────┤
│  Every HCIT days:                                               │
│    1. Notification sent to host                                 │
│    2. Host has HCRT hours to respond                           │
│    3. If no response: retry up to HCRAC times                 │
│    4. After HCRAC failures: survivors notified                  │
└─────────────────────────────────────────────────────────────────┘
                                            ↓
┌─────────────────────────────────────────────────────────────────┐
│                     WILL TRANSFER                               │
├─────────────────────────────────────────────────────────────────┤
│  1. Survivors notified                                         │
│  2. Each survivor authenticates via OTP                        │
│  3. When K authenticate: shares combined → DEK reconstructed    │
│  4. Documents decrypted → survivors can download               │
│  5. Access window expires → re-sealed                           │
└─────────────────────────────────────────────────────────────────┘

Next Steps

• Encryption — Technical encryption details
• Shamir's Secret Sharing — How SSS works
• Liveness Checks — Dead man's switch configuration
• Will Transfer Protocol — Detailed transfer flow