Menu

Twin Ledger Family Vault Security Architecture

Twin Ledger's family vault is designed to encrypt sensitive household records on the user's device before they are stored or synchronized through Twin Ledger services.

This document describes the current security architecture of the family vault, including how encryption, authentication, recovery, and sharing work in the current browser-based deployment. It is intended to describe the system accurately and conservatively, including the limits of the current model.

Design Overview

Twin Ledger separates account authentication from vault decryption.

Twin Ledger services handle account management, encrypted storage, synchronization, and family coordination. Cryptographic operations that protect vault contents occur locally on the user's device.

When a vault is unlocked, the user's device decrypts private key material locally and uses those keys to encrypt, decrypt, and sign vault records before synchronization.

Authorized household members receive access through their own key material rather than through a single shared household secret.

Twin Ledger is designed so that encrypted vault contents stored by the service are not ordinarily readable without access to user-controlled keys.

What The Vault Protects

The family vault is intended to protect sensitive household records such as:

  • Ledger entries
  • Accounts and balances
  • Budgets and planning records
  • Projects and recurring plans
  • Family-private travel budgets
  • Uploaded financial documents

Vault records are encrypted locally before storage or synchronization.

Twin Ledger services still necessarily process operational metadata required to run the system, including account identity, family membership, synchronization state, timestamps, encrypted object sizes, and related coordination data.

Key Architecture

Each user maintains their own cryptographic identity.

Twin Ledger uses recipient-specific key wrapping for shared vault access. Vault data is encrypted with data keys, and those data keys are separately wrapped for each authorized household member.

This allows family members to access shared vault data using their own keys without requiring a shared household private key.

Encrypted vault payloads and sharing bundles may also be signed to improve integrity verification and stale-data detection.

Twin Ledger distinguishes between structured vault data and large document-style uploads:

  • DATA keys protect structured records such as ledgers, budgets, and planning data.
  • DOC keys protect uploaded files such as receipts and invoices.

The distinction is operational rather than cryptographic. Both are encrypted using recipient-specific access controls, but document-style objects are handled differently for caching and rotation efficiency.

Cryptography

The standard vault path currently uses established Web Crypto primitives, including:

  • AES-GCM for symmetric encryption
  • SHA-256 for hashing and integrity-related operations
  • PBKDF2-SHA-256 for password-based key wrapping
  • P-256 elliptic-curve cryptography for key agreement and signing

Twin Ledger also supports experimental modular cryptographic engines, including selected hybrid and post-quantum key flows in limited parts of the system.

These capabilities primarily exist to support architectural flexibility and operational experience with post-quantum-style key management models. Many post-quantum schemes use different assumptions and abstraction boundaries than traditional Diffie-Hellman-based systems, and Twin Ledger's architecture is designed to accommodate those differences over time.

Twin Ledger does not currently recommend post-quantum modes for most users, and those modes should not be interpreted as a universal post-quantum guarantee across all vault operations, recovery paths, or account states.

Authentication

Twin Ledger uses an SRP-style password-authenticated flow for account sign-in.

The goal of this design is to authenticate users without transmitting plaintext passwords to the service or storing plaintext passwords in service infrastructure.

Successful authentication establishes account access, but vault decryption remains separate. After sign-in, vault keys are decrypted locally on the user's device using password-derived key material.

Like other password-authenticated systems, this model does not protect against phishing, compromised devices, malicious browser code, or users voluntarily disclosing credentials.

Recovery

Recovery is based on recovery words generated locally on the user's device.

Twin Ledger does not store recovery words as plaintext.

Recovery operations require proof of possession of recovery-related signing keys derived from those recovery words. Recovery words therefore remain high-value secrets: anyone who obtains them may be able to recover vault access.

Local Device State

The current browser deployment uses encrypted local session state to reduce the need for repeated vault unlock operations.

Encrypted structured vault records may also be cached locally to improve synchronization performance and responsiveness.

This browser-local storage is intended as a usability and synchronization mechanism rather than a hardened secure-storage boundary. Large document blobs protected by DOC keys are not included in the local structured vault cache.

Browser Security Model

The current Twin Ledger vault operates within the browser security model.

Client-side encryption meaningfully reduces exposure from passive encrypted-storage compromise, but the browser runtime, delivered application code, local session state, and cryptographic operations all exist within the same trust boundary.

As a result, a compromised browser environment, malicious extension, compromised application delivery path, or unlocked malicious session may still expose decrypted vault contents.

For this reason, the current browser deployment should be understood as a client-side encrypted web application rather than as a system with a fully independent trusted-signer boundary.

A stronger trusted-key architecture would require packaged-client controls such as platform secure storage, controlled update delivery, and key operations isolated from ordinary browser state.

The current threat model for most users is still dominated by ordinary endpoint compromise, phishing, malicious browser code, weak credentials, and recovery-word exposure rather than by practical attacks against widely deployed elliptic-curve cryptography. Twin Ledger's experimental post-quantum support should therefore be understood primarily as long-term architectural preparation and operational experience rather than as a claim that current consumer browser deployments require immediate migration away from conventional elliptic-curve systems.

Integrity And Synchronization

Twin Ledger uses signatures, freshness checks, and consistency validation to improve detection of tampering and stale local state during synchronization.

These mechanisms improve integrity guarantees for ordinary collaboration and synchronization workflows, but they are not equivalent to a public append-only transparency system and do not eliminate the possibility of service-side rollback or denial-of-service behavior.

Sharing Boundaries

Twin Ledger separates family-private financial records from collaborative itinerary-sharing workflows.

Shared travel coordination does not automatically expose household financial information unless a workflow explicitly shares that data.

Departure Day

Departure Day is integrated with Twin Ledger and provides the travel planning back end for the platform. It does not use the family vault architecture described here. It is a separate, server-readable travel product, and the encryption, key-wrapping, and recovery model in this document do not apply to it.

This is a deliberate design choice. Departure Day supports collaboration across travelers, advisors, and traveling companions who may not share a household or a set of keys. End-to-end encryption would remove the server-side recovery paths those users depend on and make ordinary account recovery, support, and troubleshooting impossible to provide.

Departure Day instead relies on conventional protections such as encryption in transit and at rest, least-privilege handling, and SRP-style password authentication, so plaintext passwords are not transmitted to or stored by the service. When a Twin Ledger household plans travel from inside the vault, the private financial records stay in the encrypted vault; only the itinerary items the household chooses to share are placed into Departure Day's server-readable model.

Threat Model

Twin Ledger's security model is primarily designed to reduce exposure from passive compromise of encrypted vault storage.

The system is intended to protect encrypted vault contents from unauthorized access by parties who do not possess the necessary user-controlled keys.

The model also attempts to improve integrity verification, recipient-specific sharing, and recovery authorization through signed operations and key-possession checks.

Like other browser-based encrypted systems, Twin Ledger depends heavily on the integrity of:

  • The user's device
  • The browser environment
  • Delivered application code
  • User credentials and recovery material

The current model does not fully mitigate:

  • Malware on the user's device
  • Malicious browser extensions
  • Phishing attacks
  • Compromised browser sessions
  • Active attacks against application delivery
  • Physical access to unlocked devices
  • Denial-of-service attacks
  • Complete concealment of operational metadata

If the browser environment is compromised while the vault is unlocked, client-side encryption cannot prevent exposure of decrypted vault contents because the application must access plaintext in order to render and edit records.

Similarly, if recovery words are disclosed, an attacker may be able to recover vault access regardless of encrypted storage protections.

Security Summary

Twin Ledger's family vault is designed to encrypt sensitive household records locally before storage while supporting recipient-specific sharing and recovery based on proof of key possession.

The current architecture is strongest against passive exposure of encrypted vault storage and weaker against endpoint compromise, malicious browser environments, phishing, and active infrastructure attacks.

The security of the system therefore depends not only on cryptography, but also on safe devices, protected credentials, secure recovery handling, and correct operation of the surrounding service infrastructure.